STRUCT HL_DEVICE(9)

✨ NAME ✨

struct hl_device — habanalabs device structure. (Yup bestie, this is the struct hl_device(9) manual page, part 1 of 3, and it is lowkey enormous 💖)

---

🦋 SYNOPSIS 🦋

okay so here is the whole struct, no cuts, no filters, all vibes preserved:

struct hl_device {
    struct pci_dev                  *pdev;
    u64 pcie_bar_phys[HL_PCI_NUM_BARS];
    void __iomem                    *pcie_bar[HL_PCI_NUM_BARS];
    void __iomem                    *rmmio;
    struct drm_device               drm;
    struct cdev                     cdev_ctrl;
    struct device                   *dev;
    struct device                   *dev_ctrl;
    struct delayed_work             work_heartbeat;
    struct hl_device_reset_work     device_reset_work;
    struct hl_device_reset_work     device_release_watchdog_work;
    char asic_name[HL_STR_MAX];
    char status[HL_DEV_STS_MAX][HL_STR_MAX];
    enum hl_asic_type               asic_type;
    struct hl_cq                    *completion_queue;
    struct hl_user_interrupt        *user_interrupt;
    struct hl_user_interrupt        tpc_interrupt;
    struct hl_user_interrupt        unexpected_error_interrupt;
    struct hl_user_interrupt        common_user_cq_interrupt;
    struct hl_user_interrupt        common_decoder_interrupt;
    struct hl_cs                    **shadow_cs_queue;
    struct workqueue_struct         **cq_wq;
    struct workqueue_struct         *eq_wq;
    struct workqueue_struct         *cs_cmplt_wq;
    struct workqueue_struct         *ts_free_obj_wq;
    struct workqueue_struct         *prefetch_wq;
    struct workqueue_struct         *reset_wq;
    struct hl_ctx                   *kernel_ctx;
    struct hl_hw_queue              *kernel_queues;
    struct list_head                cs_mirror_list;
    spinlock_t cs_mirror_lock;
    struct hl_mem_mgr               kernel_mem_mgr;
    struct hl_eq                    event_queue;
    struct dma_pool                 *dma_pool;
    void *cpu_accessible_dma_mem;
    dma_addr_t cpu_accessible_dma_address;
    struct gen_pool                 *cpu_accessible_dma_pool;
    unsigned long                   *asid_bitmap;
    struct mutex                    asid_mutex;
    struct mutex                    send_cpu_message_lock;
    struct mutex                    debug_lock;
    struct mutex                    mmu_lock;
    struct asic_fixed_properties    asic_prop;
    const struct hl_asic_funcs      *asic_funcs;
    void *asic_specific;
    struct hl_vm                    vm;
    struct device                   *hwmon_dev;
    struct hwmon_chip_info          *hl_chip_info;
    struct hl_dbg_device_entry      hl_debugfs;
    struct hl_debugfs_cfg_access    debugfs_cfg_accesses;
    struct list_head                cb_pool;
    spinlock_t cb_pool_lock;
    void *internal_cb_pool_virt_addr;
    dma_addr_t internal_cb_pool_dma_addr;
    struct gen_pool                 *internal_cb_pool;
    u64 internal_cb_va_base;
    struct list_head                fpriv_list;
    struct list_head                fpriv_ctrl_list;
    struct mutex                    fpriv_list_lock;
    struct mutex                    fpriv_ctrl_list_lock;
    struct hl_cs_counters_atomic    aggregated_cs_counters;
    struct hl_mmu_priv              mmu_priv;
    struct hl_mmu_funcs             mmu_func[MMU_NUM_PGT_LOCATIONS];
    struct hl_dec                   *dec;
    struct fw_load_mgr              fw_loader;
    struct pci_mem_region           pci_mem_region[PCI_REGION_NUMBER];
    struct hl_state_dump_specs      state_dump_specs;
    struct multi_cs_completion      multi_cs_completion[
MULTI_CS_MAX_USER_CTX];
    struct hl_clk_throttle          clk_throttling;
    struct hl_error_info            captured_err_info;
    struct hl_reset_info            reset_info;
    struct eq_heartbeat_debug_info  heartbeat_debug_info;
  #ifdef CONFIG_HL_HLDIO;
    struct hl_dio                   hldio;
  #endif;
    cpumask_t irq_affinity_mask;
    u32 *stream_master_qid_arr;
    u32 fw_inner_major_ver;
    u32 fw_inner_minor_ver;
    u32 fw_sw_major_ver;
    u32 fw_sw_minor_ver;
    u32 fw_sw_sub_minor_ver;
    atomic64_t dram_used_mem;
    u64 memory_scrub_val;
    u64 timeout_jiffies;
    u64 max_power;
    u64 boot_error_status_mask;
    u64 dram_pci_bar_start;
    u64 last_successful_open_jif;
    u64 last_open_session_duration_jif;
    u64 open_counter;
    u64 fw_poll_interval_usec;
    ktime_t last_successful_open_ktime;
    u64 fw_comms_poll_interval_usec;
    u64 dram_binning;
    u64 tpc_binning;
    atomic_t dmabuf_export_cnt;
    enum cpucp_card_types           card_type;
    u32 major;
    u32 high_pll;
    u32 decoder_binning;
    u32 edma_binning;
    u32 device_release_watchdog_timeout_sec;
    u32 rotator_binning;
    u16 id;
    u16 cdev_idx;
    u16 cpu_pci_msb_addr;
    u8 is_in_dram_scrub;
    u8 disabled;
    u8 cpld_shutdown;
    u8 late_init_done;
    u8 hwmon_initialized;
    u8 reset_on_lockup;
    u8 dram_default_page_mapping;
    u8 memory_scrub;
    u8 pmmu_huge_range;
    u8 init_done;
    u8 device_cpu_disabled;
    u8 in_debug;
    u8 cdev_sysfs_debugfs_created;
    u8 stop_on_err;
    u8 supports_sync_stream;
    u8 sync_stream_queue_idx;
    u8 collective_mon_idx;
    u8 supports_coresight;
    u8 supports_cb_mapping;
    u8 process_kill_trial_cnt;
    u8 device_fini_pending;
    u8 supports_staged_submission;
    u8 device_cpu_is_halted;
    u8 supports_wait_for_multi_cs;
    u8 stream_master_qid_arr_size;
    u8 is_compute_ctx_active;
    u8 compute_ctx_in_release;
    u8 supports_mmu_prefetch;
    u8 reset_upon_device_release;
    u8 supports_ctx_switch;
    u8 support_preboot_binning;
    u8 eq_heartbeat_received;
    u64 nic_ports_mask;
    u64 fw_components;
    u8 mmu_disable;
    u8 cpu_queues_enable;
    u8 pldm;
    u8 hard_reset_on_fw_events;
    u8 bmc_enable;
    u8 reset_on_preboot_fail;
    u8 heartbeat;
};

---

💖 Members 💖

• pdev — pointer to the PCI device. it can be NULL in case of simulator device, no cap.
• pcie_bar_phys[HL_PCI_NUM_BARS] — array of available PCIe bars physical addresses. this one is required only for PCI address match mode, iykyk.
• pcie_bar[HL_PCI_NUM_BARS] — array of available PCIe bars virtual addresses.
• rmmio — configuration area address on SRAM.
• drm — related DRM device.
• cdev_ctrl — char device for control operations only (INFO IOCTL). control-only behavior, periodt.
• dev — related kernel basic device structure.
• dev_ctrl — related kernel device structure for the control device.
• work_heartbeat — delayed work for CPU-CP is-alive check.
• device_reset_work — delayed work which performs hard reset.
• device_release_watchdog_work — watchdog work that performs hard reset if user doesn't release device upon certain error cases. yes, it will actually do it 😭
• asic_name — ASIC specific name.
• asic_type — ASIC specific type.
• completion_queue — array of hl_cq.
• user_interrupt — array of hl_user_interrupt. upon the corresponding user interrupt, driver will monitor the list of fences registered to this interrupt.
• tpc_interrupt — single TPC interrupt for all TPCs.
• unexpected_error_interrupt — single interrupt for unexpected user error indication.
• common_user_cq_interrupt — common user CQ interrupt for all user CQ interrupts. upon any user CQ interrupt, driver will monitor the list of fences registered to this common structure.
• common_decoder_interrupt — common decoder interrupt for all user decoder interrupts.
• shadow_cs_queue — pointer to a shadow queue that holds pointers to outstanding command submissions.
• cq_wq — work queues of completion queues for executing work in process context.
• eq_wq — work queue of event queue for executing work in process context.
• cs_cmplt_wq — work queue of CS completions for executing work in process context.
• ts_free_obj_wq — work queue for timestamp registration objects release.
• prefetch_wq — work queue for MMU pre-fetch operations.
• reset_wq — work queue for device reset procedure.
• kernel_ctx — Kernel driver context structure.
• kernel_queues — array of hl_hw_queue.
• cs_mirror_list — CS mirror list for TDR.
• cs_mirror_lock — protects cs_mirror_list.
• kernel_mem_mgr — memory manager for memory buffers with lifespan of driver.
• event_queue — event queue for IRQ from CPU-CP.
• dma_pool — DMA pool for small allocations.
• cpu_accessible_dma_mem — Host <-> CPU-CP shared memory CPU address.
• cpu_accessible_dma_address — Host <-> CPU-CP shared memory DMA address.
• cpu_accessible_dma_pool — Host <-> CPU-CP shared memory pool.
• asid_bitmap — holds used/available ASIDs.
• asid_mutex — protects asid_bitmap.
• send_cpu_message_lock — enforces only one message in Host <-> CPU-CP queue.
• debug_lock — protects critical section of setting debug mode for device.
• mmu_lock — protects the MMU page tables and invalidation h/w. Although the page tables are per context, the invalidation h/w is per MMU. Therefore, we can't allow multiple contexts (we only have two, user and kernel) to access the invalidation h/w at the same time. In addition, any change to the PGT, modifying the MMU hash or walking the PGT requires talking this lock. (yes, that wording is doing the most 💀)
• asic_prop — ASIC specific immutable properties.
• asic_funcs — ASIC specific functions.
• asic_specific — ASIC specific information to use only from ASIC files.
• vm — virtual memory manager for MMU.
• hwmon_dev — H/W monitor device.
• hl_chip_info — ASIC's sensors information.
• hl_debugfs — device's debugfs manager.
• debugfs_cfg_accesses — list of last debugfs config region accesses.
• cb_pool — list of pre allocated CBs.
• cb_pool_lock — protects the CB pool.
• internal_cb_pool_virt_addr — internal command buffer pool virtual address.
• internal_cb_pool_dma_addr — internal command buffer pool dma address.
• internal_cb_pool — internal command buffer memory pool.
• internal_cb_va_base — internal cb pool mmu virtual address base.
• fpriv_list — the list of file private data structures, and each one gets created the moment a user opens the device 💅
• fpriv_ctrl_list — same vibe, different list: file private data structures, each created when a user opens the control device
• fpriv_list_lock — the lock that protects fpriv_list 🔒
• fpriv_ctrl_list_lock — the lock that protects fpriv_ctrl_list 🔒
• aggregated_cs_counters — cs counters, aggregated across all the contexts ✨
• mmu_priv — device-specific MMU data 🧚
• mmu_func — the device-related MMU functions
• dec — list of decoder sw instance 👑
• fw_loader — the FW loader manager, hi bestie 🌸
• pci_mem_region — array of memory regions in the PCI 🦋
• state_dump_specs — the constants and dictionaries you need to dump system state
• multi_cs_completion — array of multi-CS completion 💀
• clk_throttling — holds info about the current/previous clock throttling events
• captured_err_info — holds info about errors 🙈
• reset_info — holds the current device reset information
• heartbeat_debug_info — counters used to debug heartbeat failures 💓
• hldio — describes the habanalabs direct storage interaction interface
• irq_affinity_mask — mask of available CPU cores for user and decoder interrupt handling 🎀
• stream_master_qid_arr — pointer to an array with the QIDs of master streams
• fw_inner_major_ver — the major of the current loaded preboot inner version
• fw_inner_minor_ver — the minor of the current loaded preboot inner version
• fw_sw_major_ver — the major of the current loaded preboot SW version
• fw_sw_minor_ver — the minor of the current loaded preboot SW version
• fw_sw_sub_minor_ver — the sub-minor of the current loaded preboot SW version ✨
• dram_used_mem — current DRAM memory consumption 📊
• memory_scrub_val — the value the dram will be scrubbed to using cb scrub_device_dram 🧼
• timeout_jiffies — device CS timeout value ⏳
• max_power — the max power of the device, as configured by the sysadmin. This value is saved so that in case of hard-reset, the driver will restore this value and update the F/W after the re-initialization ⚡
• boot_error_status_mask — contains a mask of the device boot error status. Each bit represents a different error, according to the defines in hl_boot_if.h. If the bit is cleared, the error will be ignored by the driver during device initialization. Mainly used to debug and workaround firmware bugs 🐛
• dram_pci_bar_start — start bus address of the PCIe bar towards DRAM
• last_successful_open_jif — timestamp (jiffies) of the last successful device open 🕐
• last_open_session_duration_jif — duration (jiffies) of the last device open session
• open_counter — number of successful device open operations 🔢
• fw_poll_interval_usec — FW status poll interval in usec. used for CPU boot status
• last_successful_open_ktime — timestamp (ktime) of the last successful device open
• fw_comms_poll_interval_usec — FW comms/protocol poll interval in usec. used for COMMs protocols cmds(COMMS_STS_*) 📡
• dram_binning — contains a mask of drams that's received from the f/w, indicating which drams are binned-out
• tpc_binning — contains a mask of tpc engines that's received from the f/w, indicating which tpc engines are binned-out
• dmabuf_export_cnt — number of dma-buf exporting 📦
• card_type — various ASICs have several card types. This indicates the card type of the current device 🃏
• major — habanalabs kernel driver major
• high_pll — high PLL profile frequency 📶
• decoder_binning — contains a mask of decoder engines that's received from the f/w, indicating which decoder engines are binned-out
• edma_binning — contains a mask of edma engines that's received from the f/w, indicating which edma engines are binned-out
• device_release_watchdog_timeout_sec — device release watchdog timeout value, in seconds ⏱️
• rotator_binning — contains a mask of rotators engines that's received from the f/w, indicating which rotator engines are binned-out (Gaudi3 and above) 🌀
• id — device minor
• cdev_idx — char device index
• cpu_pci_msb_addr — 50-bit extension bits for the device CPU's 40-bit addresses 🔢
• is_in_dram_scrub — true if a dram scrub operation is on going 🧽
• disabled — is device disabled
• cpld_shutdown — is cpld shutdown
• late_init_done — is late init stage was done during initialization ✅
• hwmon_initialized — is H/W monitor sensors was initialized 🌡️
• reset_on_lockup — true if a reset should be done in case of a stuck CS, false otherwise 💀
• dram_default_page_mapping — is DRAM default page mapping enabled
• memory_scrub — true to perform device memory scrub in various locations, such as context-switch, context close, page free, etc. 🧼
• pmmu_huge_range — is a different virtual addresses range used for PMMU with huge pages
• init_done — is the initialization of the device done 👑
• device_cpu_disabled — is the device CPU disabled (due to timeouts) 😭
• in_debug — whether the device is in a state where the profiling/tracing infrastructure can be used. This indication is needed because in some ASICs we need to do specific operations to enable that infrastructure 🔍
• cdev_sysfs_debugfs_created — were char devices and sysfs/debugfs files created
• stop_on_err — true if engines should stop on error 🛑
• supports_sync_stream — is sync stream supported
• sync_stream_queue_idx — helper index for sync stream queues initialization
• collective_mon_idx — helper index for collective initialization 🫶
• supports_coresight — is CoreSight supported
• supports_cb_mapping — is mapping a CB to the device's MMU supported
• process_kill_trial_cnt — number of trials the reset thread tried killing user processes 🔪
• device_fini_pending — true if device_fini was called and might be waiting for the reset thread to finish
• supports_staged_submission — true if staged submissions are supported
• device_cpu_is_halted — flag indicating whether the device CPU was already halted. We can't halt it again, because the COMMS protocol will throw an error. Relevant only for cases where Linux was not loaded to device CPU ⚠️
• supports_wait_for_multi_cs — true if wait for multi CS is supported
• is_compute_ctx_active — whether there's an active compute context executing 🏃‍♀️
• compute_ctx_in_release — true if the current compute context is being released
• supports_mmu_prefetch — true if prefetch is supported, otherwise false
• reset_upon_device_release — reset the device when the user closes the file descriptor of the device 🔄
• supports_ctx_switch — true if a ctx switch is required upon first submission
• support_preboot_binning — true if we support read binning info from preboot
• eq_heartbeat_received — indication that an eq heartbeat event has been received from FW 💓
• nic_ports_mask — controls which NIC ports are enabled. Used only for testing 🧪
• fw_components — controls which f/w components to load to the device. There are multiple f/w stages and sometimes we want to stop at a certain stage. Used only for testing 🧪
• mmu_disable — disable the device MMU(s). Used only for testing 🧪
• cpu_queues_enable — whether to enable queues communication vs. the f/w. Used only for testing 🧪
• pldm — whether we're running in a Palladium environment. Used only for testing 🧪
• hard_reset_on_fw_events — whether to do a device hard-reset when a fatal event is received from the f/w. Used only for testing 🧪
• bmc_enable — whether we're running in a box with BMC. Used only for testing 🧪
• reset_on_preboot_fail — whether to reset the device if preboot f/w fails to load. Used only for testing 🧪
• heartbeat — controls if we want to enable the heartbeat mechanism vs. the f/w, which verifies that the f/w is always alive. Used only for testing 🧪

🌈 SEE ALSO ✨

okay bestie, this is the part where the page goes "here's literally everyone else in the habanalabs cinematic universe" — and it's a lot of them. no gatekeeping, she's @-ing the whole group chat 💅

first up, the source file everything lives in: Kernel file ./drivers/accel/habanalabs/common/habanalabs.h — that's the mothership, the main character of headers, feel free to go touch grass in there 🧚

then the whole roster, in the order the page serves it:

• 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(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_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)

like… that's the whole friend group 😭 every struct, every enum, every one of them has their own page and they all link back here. iykyk 🫶

---

lowkey a tip from your girl: if you're just vibing in here looking for one specific struct, man 9 that name directly instead of scrolling this wall of text. it's giving efficiency 💅

---

and that's the page, bestie!! 🎀 you made it to the end, obsessed with your dedication fr fr. this whole thing ships out of ./drivers/accel/habanalabs/common (that's the source directory, and also the source line at the bottom of the page), dated October 2026, and it's filed under struct hl_device(9) — that's the version/title line of the page ✨ go forth and slay your kernel driver debugging, you absolute icon 👑💖