STRUCT HL_CTX(9)

okay bestie, welcome to struct hl_ctx(9) — the Kernel API Manual page for the user/kernel context. grab a strawberry 🍓, because we are going through every single field and not skipping a one.

✨ NAME ✨

struct hl_ctx — user/kernel context. that’s the name, periodt 💅

💖 SYNOPSIS 💖

here’s the whole struct, copied exactly because we do not mess with code, no cap:

struct hl_ctx {
    unsigned long mem_hash[1 << (( MEM_HASH_TABLE_BITS) - 1)];
    unsigned long mmu_shadow_hash[1 << (( MMU_HASH_TABLE_BITS) - 1)];
    unsigned long hr_mmu_phys_hash[1 << (( MMU_HASH_TABLE_BITS) - 1)];
    struct hl_fpriv                 *hpriv;
    struct hl_device                *hdev;
    struct kref                     refcount;
    struct hl_fence                 **cs_pending;
    struct hl_cs_outcome_store      outcome_store;
    struct hl_va_range              *va_range[HL_VA_RANGE_TYPE_MAX];
    struct mutex                    mem_hash_lock;
    struct mutex                    hw_block_list_lock;
    struct mutex                    ts_reg_lock;
    struct list_head                debugfs_list;
    struct list_head                hw_block_mem_list;
    struct hl_cs_counters_atomic    cs_counters;
    struct gen_pool                 *cb_va_pool;
    struct hl_encaps_signals_mgr    sig_mgr;
    u64 cb_va_pool_base;
    u64 cs_sequence;
    u64 *dram_default_hops;
    spinlock_t cs_lock;
    atomic64_t dram_phys_mem;
    atomic_t thread_ctx_switch_token;
    u32 thread_ctx_switch_wait_token;
    u32 asid;
    u32 handle;
 };

🫶 Members 🫶

every member is getting its moment, bestie. no skips, no “we’ll come back to it” energy 💖

• mem_hash — holds mapping from virtual address to virtual memory area descriptor (hl_vm_phys_pg_list or hl_userptr).
• mmu_shadow_hash — holds a mapping from shadow address to pgt_info structure.
• hr_mmu_phys_hash — if host-resident MMU is used, holds a mapping from MMU-hop-page physical address to its host-resident pgt_info structure.
• hpriv — pointer to the private (Kernel Driver) data of the process (fd).
• hdev — pointer to the device structure.
• refcount — reference counter for the context. Context is released only when this hits 0. It is incremented on CS and CS_WAIT.
• cs_pending — array of hl fence objects representing pending CS.
• outcome_store — storage data structure used to remember outcomes of completed command submissions for a long time after CS id wraparound.
• va_range — holds available virtual addresses for host and dram mappings.
• mem_hash_lock — protects the mem_hash.
• hw_block_list_lock — protects the HW block memory list.
• ts_reg_lock — timestamp registration ioctls lock.
• debugfs_list — node in debugfs list of contexts.
• hw_block_mem_list — list of HW block virtual mapped addresses.
• cs_counters — context command submission counters.
• cb_va_pool — device VA pool for command buffers which are mapped to the device's MMU.
• sig_mgr — encaps signals handle manager.
• cb_va_pool_base — the base address for the device VA pool.
• cs_sequence — sequence number for CS. Value is assigned to a CS and passed to user so user could inquire about CS. It is used as index to cs_pending array.
• dram_default_hops — array that holds all hops addresses needed for default DRAM mapping.
• cs_lock — spinlock to protect cs_sequence.
• dram_phys_mem — amount of used physical DRAM memory by this context.
• thread_ctx_switch_token — token to prevent multiple threads of the same context from running the context switch phase. Only a single thread should run it.
• thread_ctx_switch_wait_token — token to prevent the threads that didn't run the context switch phase from moving to their execution phase before the context switch phase has finished.
• asid — context's unique address space ID in the device's MMU.
• handle — context's opaque handle for user.

🌈 SEE ALSO 🌈

Kernel file ./drivers/accel/habanalabs/common/habanalabs.h, plus this whole cross-reference friend group — every single one is invited to the group chat 💜:

• enum hl_mmu_page_table_location(9)
• struct iterate_module_ctx(9)
• struct hl_gen_wait_properties(9)
• struct pgt_info(9)
• enum hl_pci_match_mode(9)
• enum hl_fw_component(9)
• enum hl_fw_types(9)
• enum hl_queue_type(9)
• struct hw_queue_properties(9)
• enum vm_type(9)
• enum mmu_op_flags(9)
• enum hl_device_hw_state(9)
• struct hl_mmu_properties(9)
• struct hl_hints_range(9)
• struct asic_fixed_properties(9)
• struct hl_fence(9)
• struct hl_cs_compl(9)
• struct hl_ts_buff(9)
• struct hl_mem_mgr(9)
• struct hl_mem_mgr_fini_stats(9)
• struct hl_mmap_mem_buf_behavior(9)
• struct hl_mmap_mem_buf(9)
• struct hl_cb(9)
• struct hl_sync_stream_properties(9)
• struct hl_encaps_signals_mgr(9)
• struct hl_hw_queue(9)
• struct hl_cq(9)
• struct hl_ts_free_jobs(9)
• struct hl_user_interrupt(9)
• struct timestamp_reg_free_node(9)
• struct hl_user_pending_interrupt(9)
• struct hl_eq(9)
• struct hl_dec(9)
• enum hl_asic_type(9)
• enum hl_pm_mng_profile(9)
• enum hl_pll_frequency(9)
• struct pci_mem_region(9)
• struct static_fw_load_mgr(9)
• struct fw_response(9)
• struct dynamic_fw_load_mgr(9)
• struct pre_fw_load_props(9)
• struct fw_image_props(9)
• struct fw_load_mgr(9)
• struct engines_data(9)
• struct hl_asic_funcs(9)
• enum hl_va_range_type(9)
• struct hl_va_range(9)
• struct hl_cs_counters_atomic(9)
• struct hl_dmabuf_priv(9)
• struct hl_cs_outcome(9)
• struct hl_cs_outcome_store(9)
• struct hl_ctx_mgr(9)
• struct hl_userptr(9)
• struct hl_cs(9)
• struct hl_cs_job(9)
• struct hl_cs_parser(9)
• struct hl_vm_hash_node(9)
• struct hl_vm_hw_block_list_node(9)
• struct hl_vm_phys_pg_pack(9)
• struct hl_vm_va_block(9)
• struct hl_vm(9)
• struct hl_debug_params(9)
• struct hl_notifier_event(9)
• struct hl_fpriv(9)
• struct hl_info_list(9)
• struct hl_debugfs_entry(9)
• struct hl_dbg_device_entry(9)
• struct hl_debugfs_cfg_access_entry(9)
• struct hl_debugfs_cfg_access(9)
• struct hl_hw_obj_name_entry(9)
• struct hl_mon_state_dump(9)
• struct hl_sync_to_engine_map_entry(9)
• struct hl_sync_to_engine_map(9)
• struct hl_state_dump_specs_funcs(9)
• struct hl_state_dump_specs(9)
• struct hl_device_reset_work(9)
• struct hl_mmu_priv(9)
• struct hl_mmu_per_hop_info(9)
• struct hl_mmu_hop_info(9)
• struct hl_hr_mmu_funcs(9)
• struct hl_mmu_funcs(9)
• struct hl_prefetch_work(9)
• struct multi_cs_completion(9)
• struct multi_cs_data(9)
• struct hl_clk_throttle_timestamp(9)
• struct hl_clk_throttle(9)
• struct user_mapped_block(9)
• struct cs_timeout_info(9)
• struct undefined_opcode_info(9)
• struct page_fault_info(9)
• struct razwi_info(9)
• struct hw_err_info(9)
• struct fw_err_info(9)
• struct engine_err_info(9)
• struct hl_error_info(9)
• struct hl_reset_info(9)
• struct eq_heartbeat_debug_info(9)
• struct hl_device(9)
• struct hl_cs_encaps_sig_handle(9)
• struct hl_info_fw_err_info(9)
• hl_ioctl_t(9)
• struct hl_ioctl_desc(9)
• hl_get_sg_info(9)
• hl_mem_area_inside_range(9)
• hl_mem_area_crosses_range(9)

that’s a wrap, bestie 🫶 — source/version: ./drivers/accel/habanalabs/common, date: October 2026, manual: struct hl_ctx(9). go be iconic with your context 💅✨