Runtime Power Management¶

The i915 driver supports dynamic enabling and disabling of entire hardwareblocks at runtime. This is especially important on the display side wheresoftware is supposed to control many power gates manually on recent hardware,since on the GT side a lot of the power management is done by the hardware.But even there some manual control at the device level is required.

Since i915 supports a diverse set of platforms with a unified codebase andhardware engineers just love to shuffle functionality around between powerdomains there’s a sizeable amount of indirection required. This file providesgeneric functions to the driver for grabbing and releasing references forabstract power domains. It then maps those to the actual power wellspresent for a given platform.

intel_wakeref_tintel_runtime_pm_get_raw(structintel_runtime_pm*rpm)¶

grab a raw runtime pm reference

intel_wakeref_tintel_runtime_pm_get(structintel_runtime_pm*rpm)¶

grab a runtime pm reference

intel_wakeref_t__intel_runtime_pm_get_if_active(structintel_runtime_pm*rpm,boolignore_usecount)¶

grab a runtime pm reference if device is active

intel_wakeref_tintel_runtime_pm_get_noresume(structintel_runtime_pm*rpm)¶

grab a runtime pm reference

voidintel_runtime_pm_put_raw(structintel_runtime_pm*rpm,intel_wakeref_twref)¶

release a raw runtime pm reference

voidintel_runtime_pm_put_unchecked(structintel_runtime_pm*rpm)¶

release an unchecked runtime pm reference

voidintel_runtime_pm_put(structintel_runtime_pm*rpm,intel_wakeref_twref)¶

release a runtime pm reference

voidintel_runtime_pm_enable(structintel_runtime_pm*rpm)¶

enable runtime pm

voidintel_uncore_forcewake_get(structintel_uncore*uncore,enumforcewake_domainsfw_domains)¶

grab forcewake domain references

voidintel_uncore_forcewake_user_get(structintel_uncore*uncore)¶

claim forcewake on behalf of userspace

voidintel_uncore_forcewake_user_put(structintel_uncore*uncore)¶

release forcewake on behalf of userspace

voidintel_uncore_forcewake_get__locked(structintel_uncore*uncore,enumforcewake_domainsfw_domains)¶

grab forcewake domain references

voidintel_uncore_forcewake_put(structintel_uncore*uncore,enumforcewake_domainsfw_domains)¶

release a forcewake domain reference

voidintel_uncore_forcewake_flush(structintel_uncore*uncore,enumforcewake_domainsfw_domains)¶

flush the delayed release

voidintel_uncore_forcewake_put__locked(structintel_uncore*uncore,enumforcewake_domainsfw_domains)¶

release forcewake domain references

int__intel_wait_for_register_fw(structintel_uncore*uncore,i915_reg_treg,u32mask,u32value,unsignedintfast_timeout_us,unsignedintslow_timeout_ms,u32*out_value)¶

wait until register matches expected state

(intel_uncore_read_fw(uncore, reg) & mask) == value

int__intel_wait_for_register(structintel_uncore*uncore,i915_reg_treg,u32mask,u32value,unsignedintfast_timeout_us,unsignedintslow_timeout_ms,u32*out_value)¶

wait until register matches expected state

(intel_uncore_read(uncore, reg) & mask) == value

enumforcewake_domainsintel_uncore_forcewake_for_reg(structintel_uncore*uncore,i915_reg_treg,unsignedintop)¶

which forcewake domains are needed to access a register

Interrupt Handling¶

These functions provide the basic support for enabling and disabling theinterrupt handling support. There’s a lot more functionality in i915_irq.cand related files, but that will be described in separate chapters.

voidintel_irq_init(structdrm_i915_private*dev_priv)¶

initializes irq support

voidintel_irq_suspend(structdrm_i915_private*i915)¶

Suspend interrupts

voidintel_irq_resume(structdrm_i915_private*i915)¶

Resume interrupts

Intel GVT-g Guest Support(vGPU)¶

Intel GVT-g is a graphics virtualization technology which shares theGPU among multiple virtual machines on a time-sharing basis. Eachvirtual machine is presented a virtual GPU (vGPU), which has equivalentfeatures as the underlying physical GPU (pGPU), so i915 driver can runseamlessly in a virtual machine. This file provides vGPU specificoptimizations when running in a virtual machine, to reduce the complexityof vGPU emulation and to improve the overall performance.

A primary function introduced here is so-called “address space ballooning”technique. Intel GVT-g partitions global graphics memory among multiple VMs,so each VM can directly access a portion of the memory without hypervisor’sintervention, e.g. filling textures or queuing commands. However with thepartitioning an unmodified i915 driver would assume a smaller graphicsmemory starting from address ZERO, then requires vGPU emulation module totranslate the graphics address between ‘guest view’ and ‘host view’, forall registers and command opcodes which contain a graphics memory address.To reduce the complexity, Intel GVT-g introduces “address space ballooning”,by telling the exact partitioning knowledge to each guest i915 driver, whichthen reserves and prevents non-allocated portions from allocation. Thus vGPUemulation module only needs to scan and validate graphics addresses withoutcomplexity of address translation.

voidintel_vgpu_detect(structdrm_i915_private*dev_priv)¶

detect virtual GPU

voidintel_vgt_deballoon(structi915_ggtt*ggtt)¶

deballoon reserved graphics address trunks

intintel_vgt_balloon(structi915_ggtt*ggtt)¶

balloon out reserved graphics address trunks

                       vGPU1 view         Host view            0 ------> +-----------+     +-----------+              ^       |###########|     |   vGPU3   |              |       |###########|     +-----------+              |       |###########|     |   vGPU2   |              |       +-----------+     +-----------+       mappable GM    | available | ==> |   vGPU1   |              |       +-----------+     +-----------+              |       |###########|     |           |              v       |###########|     |   Host    |              +=======+===========+     +===========+              ^       |###########|     |   vGPU3   |              |       |###########|     +-----------+              |       |###########|     |   vGPU2   |              |       +-----------+     +-----------+     unmappable GM    | available | ==> |   vGPU1   |              |       +-----------+     +-----------+              |       |###########|     |           |              |       |###########|     |   Host    |              v       |###########|     |           |total GM size ------> +-----------+     +-----------+

Intel GVT-g Host Support(vGPU device model)¶

Intel GVT-g is a graphics virtualization technology which shares theGPU among multiple virtual machines on a time-sharing basis. Eachvirtual machine is presented a virtual GPU (vGPU), which has equivalentfeatures as the underlying physical GPU (pGPU), so i915 driver can runseamlessly in a virtual machine.

To virtualize GPU resources GVT-g driver depends on hypervisor technologye.g KVM/VFIO/mdev, Xen, etc. to provide resource access trapping capabilityand be virtualized within GVT-g device module. More architectural designdoc is available onhttps://github.com/intel/gvt-linux/wiki.

intintel_gvt_init(structdrm_i915_private*dev_priv)¶

initialize GVT components

voidintel_gvt_driver_remove(structdrm_i915_private*dev_priv)¶

cleanup GVT components when i915 driver is unbinding

voidintel_gvt_resume(structdrm_i915_private*dev_priv)¶

GVT resume routine wrapper

Workarounds¶

Hardware workarounds are register programming documented to be executed inthe driver that fall outside of the normal programming sequences for aplatform. There are some basic categories of workarounds, depending onhow/when they are applied:

• Context workarounds: workarounds that touch registers that aresaved/restored to/from the HW context image. The list is emitted (via LoadRegister Immediate commands) once when initializing the device and saved inthe default context. That default context is then used on every contextcreation to have a “primed golden context”, i.e. a context image thatalready contains the changes needed to all the registers.

  Context workarounds should be implemented in the *_ctx_workarounds_init()variants respective to the targeted platforms.

• Engine workarounds: the list of these WAs is applied whenever the specificengine is reset. It’s also possible that a set of engine classes share acommon power domain and they are reset together. This happens on someplatforms with render and compute engines. In this case (at least) one ofthem need to keeep the workaround programming: the approach taken in thedriver is to tie those workarounds to the first compute/render engine thatis registered. When executing with GuC submission, engine resets areoutside of kernel driver control, hence the list of registers involved inwritten once, on engine initialization, and then passed to GuC, thatsaves/restores their values before/after the reset takes place. Seedrivers/gpu/drm/i915/gt/uc/intel_guc_ads.c for reference.

  Workarounds for registers specific to RCS and CCS should be implemented inrcs_engine_wa_init() andccs_engine_wa_init(), respectively; those forregisters belonging to BCS, VCS or VECS should be implemented inxcs_engine_wa_init(). Workarounds for registers not belonging to a specificengine’s MMIO range but that are part of of the common RCS/CCS reset domainshould be implemented ingeneral_render_compute_wa_init(). The settingsabout the CCS load balancing should be added inccs_engine_wa_mode().

• GT workarounds: the list of these WAs is applied whenever these registersrevert to their default values: on GPU reset, suspend/resume[1], etc.

  GT workarounds should be implemented in the *_gt_workarounds_init()variants respective to the targeted platforms.

• Register whitelist: some workarounds need to be implemented in userspace,but need to touch privileged registers. The whitelist in the kernelinstructs the hardware to allow the access to happen. From the kernel side,this is just a special case of a MMIO workaround (as we write the list ofthese to/be-whitelisted registers to some special HW registers).

  Register whitelisting should be done in the *_whitelist_build() variantsrespective to the targeted platforms.

• Workaround batchbuffers: buffers that get executed automatically by thehardware on every HW context restore. These buffers are created andprogrammed in the default context so the hardware always go through thoseprogramming sequences when switching contexts. The support for workaroundbatchbuffers is enabled these hardware mechanisms:

  1. INDIRECT_CTX: A batchbuffer and an offset are provided in the defaultcontext, pointing the hardware to jump to that location when that offsetis reached in the context restore. Workaround batchbuffer in the drivercurrently uses this mechanism for all platforms.

  2. BB_PER_CTX_PTR: A batchbuffer is provided in the default context,pointing the hardware to a buffer to continue executing after theengine registers are restored in a context restore sequence. This iscurrently not used in the driver.

• Other: There are WAs that, due to their nature, cannot be applied from acentral place. Those are peppered around the rest of the code, as needed.Workarounds related to the display IP are the main example.

Technically, some registers are powercontext saved & restored, so theysurvive a suspend/resume. In practice, writing them again is not toocostly and simplifies things, so it’s the approach taken in the driver.

Mode Setting Infrastructure¶

The i915 driver is thus far the only DRM driver which doesn’t use thecommon DRM helper code to implement mode setting sequences. Thus it hasits own tailor-made infrastructure for executing a display configurationchange.

Frontbuffer Tracking¶

Many features require us to track changes to the currently activefrontbuffer, especially rendering targeted at the frontbuffer.

To be able to do so we track frontbuffers using a bitmask for all possiblefrontbuffer slots throughintel_frontbuffer_track(). The functions in thisfile are then called when the contents of the frontbuffer are invalidated,when frontbuffer rendering has stopped again to flush out all the changesand when the frontbuffer is exchanged with a flip. Subsystems interested infrontbuffer changes (e.g. PSR, FBC, DRRS) should directly put their callbacksinto the relevant places and filter for the frontbuffer slots that they areinterested int.

On a high level there are two types of powersaving features. The first onework like a special cache (FBC and PSR) and are interested when they shouldstop caching and when to restart caching. This is done by placing callbacksinto the invalidate and the flush functions: At invalidate the caching mustbe stopped and at flush time it can be restarted. And maybe they need to knowwhen the frontbuffer changes (e.g. when the hw doesn’t initiate an invalidateand flush on its own) which can be achieved with placing callbacks into theflip functions.

The other type of display power saving feature only cares about busyness(e.g. DRRS). In that case all three (invalidate, flush and flip) indicatebusyness. There is no direct way to detect idleness. Instead an idle timerwork delayed work should be started from the flush and flip functions andcancelled as soon as busyness is detected.

boolintel_frontbuffer_invalidate(structintel_frontbuffer*front,enumfb_op_originorigin)¶

invalidate frontbuffer object

voidintel_frontbuffer_flush(structintel_frontbuffer*front,enumfb_op_originorigin)¶

flush frontbuffer object

voidfrontbuffer_flush(structintel_display*display,unsignedintfrontbuffer_bits,enumfb_op_originorigin)¶

flush frontbuffer

voidintel_frontbuffer_flip(structintel_display*display,unsignedfrontbuffer_bits)¶

synchronous frontbuffer flip

voidintel_frontbuffer_queue_flush(structintel_frontbuffer*front)¶

queue flushing frontbuffer object

voidintel_frontbuffer_track(structintel_frontbuffer*old,structintel_frontbuffer*new,unsignedintfrontbuffer_bits)¶

update frontbuffer tracking

Display FIFO Underrun Reporting¶

The i915 driver checks for display fifo underruns using the interrupt signalsprovided by the hardware. This is enabled by default and fairly useful todebug display issues, especially watermark settings.

If an underrun is detected this is logged into dmesg. To avoid flooding logsand occupying the cpu underrun interrupts are disabled after the firstoccurrence until the next modeset on a given pipe.

Note that underrun detection on gmch platforms is a bit more ugly since thereis no interrupt (despite that the signalling bit is in the PIPESTAT pipeinterrupt register). Also on some other platforms underrun interrupts areshared, which means that if we detect an underrun we need to disable underrunreporting on all pipes.

The code also supports underrun detection on the PCH transcoder.

boolintel_set_cpu_fifo_underrun_reporting(structintel_display*display,enumpipepipe,boolenable)¶

set cpu fifo underrun reporting state

boolintel_set_pch_fifo_underrun_reporting(structintel_display*display,enumpipepch_transcoder,boolenable)¶

set PCH fifo underrun reporting state

voidintel_cpu_fifo_underrun_irq_handler(structintel_display*display,enumpipepipe)¶

handle CPU fifo underrun interrupt

voidintel_pch_fifo_underrun_irq_handler(structintel_display*display,enumpipepch_transcoder)¶

handle PCH fifo underrun interrupt

voidintel_check_cpu_fifo_underruns(structintel_display*display)¶

check for CPU fifo underruns immediately

voidintel_check_pch_fifo_underruns(structintel_display*display)¶

check for PCH fifo underruns immediately

Plane Configuration¶

This section covers plane configuration and composition with the primaryplane, sprites, cursors and overlays. This includes the infrastructureto do atomic vsync’ed updates of all this state and also tightly coupledtopics like watermark setup and computation, framebuffer compression andpanel self refresh.

Atomic Plane Helpers¶

The functions here are used by the atomic plane helper functions toimplement legacy plane updates (i.e., drm_plane->update_plane() anddrm_plane->disable_plane()). This allows plane updates to use theatomic state infrastructure and perform plane updates as separateprepare/check/commit/cleanup steps.

voidintel_plane_destroy(structdrm_plane*plane)¶

destroy a plane

structdrm_plane_state*intel_plane_duplicate_state(structdrm_plane*plane)¶

duplicate plane state

voidintel_plane_destroy_state(structdrm_plane*plane,structdrm_plane_state*state)¶

destroy plane state

intintel_prepare_plane_fb(structdrm_plane*_plane,structdrm_plane_state*_new_plane_state)¶

Prepare fb for usage on plane

voidintel_cleanup_plane_fb(structdrm_plane*plane,structdrm_plane_state*_old_plane_state)¶

Cleans up an fb after plane use

Asynchronous Page Flip¶

Asynchronous page flip is the implementation for the DRM_MODE_PAGE_FLIP_ASYNCflag. Currently async flip is only supported via the drmModePageFlip IOCTL.Correspondingly, support is currently added for primary plane only.

Async flip can only change the plane surface address, so anything elsechanging is rejected from theintel_async_flip_check_hw() function.Once this check is cleared, flip done interrupt is enabled usingtheintel_crtc_enable_flip_done() function.

As soon as the surface address register is written, flip done interrupt isgenerated and the requested events are sent to the userspace in the interrupthandler itself. The timestamp and sequence sent during the flip done eventcorrespond to the last vblank and have no relation to the actual time whenthe flip done event was sent.

Output Probing¶

This section covers output probing and related infrastructure like thehotplug interrupt storm detection and mitigation code. Note that thei915 driver still uses most of the common DRM helper code for outputprobing, so those sections fully apply.

Hotplug¶

Simply put, hotplug occurs when a display is connected to or disconnectedfrom the system. However, there may be adapters and docking stations andDisplay Port short pulses and MST devices involved, complicating matters.

Hotplug in i915 is handled in many different levels of abstraction.

The platform dependent interrupt handling code in i915_irq.c enables,disables, and does preliminary handling of the interrupts. The interrupthandlers gather the hotplug detect (HPD) information from relevant registersinto a platform independent mask of hotplug pins that have fired.

The platform independent interrupt handlerintel_hpd_irq_handler() inintel_hotplug.c does hotplug irq storm detection and mitigation, and passesfurther processing to appropriate bottom halves (Display Port specific andregular hotplug).

The Display Port work functioni915_digport_work_func() calls intointel_dp_hpd_pulse() via hooks, which handles DP short pulses and DP MST longpulses, with failures and non-MST long pulses triggering regular hotplugprocessing on the connector.

The regular hotplug work functioni915_hotplug_work_func() calls connectordetect hooks, and, if connector status changes, triggers sending of hotpluguevent to userspace viadrm_kms_helper_hotplug_event().

Finally, the userspace is responsible for triggering a modeset upon receivingthe hotplug uevent, disabling or enabling the crtc as needed.

The hotplug interrupt storm detection and mitigation code keeps track of thenumber of interrupts per hotplug pin per a period of time, and if the numberof interrupts exceeds a certain threshold, the interrupt is disabled for awhile before being re-enabled. The intention is to mitigate issues raisingfrom broken hardware triggering massive amounts of interrupts and grindingthe system to a halt.

Current implementation expects that hotplug interrupt storm will not beseen when display port sink is connected, hence on platforms whose DPcallback is handled by i915_digport_work_func reenabling of hpd is notperformed (it was never expected to be disabled in the first place ;) )this is specific to DP sinks handled by this routine and any other displaysuch as HDMI or DVI enabled on the same port will have proper logic sinceit will use i915_hotplug_work_func where this logic is handled.

enumhpd_pinintel_hpd_pin_default(enumportport)¶

return default pin associated with certain port.

boolintel_hpd_irq_storm_detect(structintel_display*display,enumhpd_pinpin,boollong_hpd)¶

gather stats and detect HPD IRQ storm on a pin

voidintel_hpd_trigger_irq(structintel_digital_port*dig_port)¶

trigger an hpd irq event for a port

voidintel_hpd_irq_handler(structintel_display*display,u32pin_mask,u32long_mask)¶

main hotplug irq handler

voidintel_hpd_init(structintel_display*display)¶

initializes and enables hpd support

voidintel_hpd_poll_enable(structintel_display*display)¶

enable polling for connectors with hpd

voidintel_hpd_poll_disable(structintel_display*display)¶

disable polling for connectors with hpd

voidintel_hpd_block(structintel_encoder*encoder)¶

Block handling of HPD IRQs on an HPD pin

voidintel_hpd_unblock(structintel_encoder*encoder)¶

Unblock handling of HPD IRQs on an HPD pin

voidintel_hpd_clear_and_unblock(structintel_encoder*encoder)¶

Unblock handling of new HPD IRQs on an HPD pin

High Definition Audio¶

The graphics and audio drivers together support High Definition Audio overHDMI and Display Port. The audio programming sequences are divided into audiocodec and controller enable and disable sequences. The graphics driverhandles the audio codec sequences, while the audio driver handles the audiocontroller sequences.

The disable sequences must be performed before disabling the transcoder orport. The enable sequences may only be performed after enabling thetranscoder and port, and after completed link training. Therefore the audioenable/disable sequences are part of the modeset sequence.

The codec and controller sequences could be done either parallel or serial,but generally the ELDV/PD change in the codec sequence indicates to the audiodriver that the controller sequence should start. Indeed, most of theco-operation between the graphics and audio drivers is handled via audiorelated registers. (The notable exception is the power management, notcovered here.)

The structi915_audio_component is used to interact between the graphicsand audio drivers. The structi915_audio_component_opsops in it isdefined in graphics driver and called in audio driver. Thestructi915_audio_component_audio_opsaudio_ops is called from i915 driver.

voidintel_audio_codec_enable(structintel_encoder*encoder,conststructintel_crtc_state*crtc_state,conststructdrm_connector_state*conn_state)¶

Enable the audio codec for HD audio

voidintel_audio_codec_disable(structintel_encoder*encoder,conststructintel_crtc_state*old_crtc_state,conststructdrm_connector_state*old_conn_state)¶

Disable the audio codec for HD audio

voidintel_audio_hooks_init(structintel_display*display)¶

Set up chip specific audio hooks

voidintel_audio_component_init(structintel_display*display)¶

initialize and register the audio component

voidintel_audio_component_cleanup(structintel_display*display)¶

deregister the audio component

voidintel_audio_init(structintel_display*display)¶

Initialize the audio driver either using component framework or using lpe audio bridge

voidintel_audio_deinit(structintel_display*display)¶

deinitialize the audio driver

structi915_audio_component¶

Used for direct communication between i915 and hda drivers

struct i915_audio_component {    struct drm_audio_component      base;    int aud_sample_rate[MAX_PORTS];};

Intel HDMI LPE Audio Support¶

Motivation:Atom platforms (e.g. valleyview and cherryTrail) integrates a DMA-basedinterface as an alternative to the traditional HDaudio path. While thismode is unrelated to the LPE aka SST audio engine, the documentation refersto this mode as LPE so we keep this notation for the sake of consistency.

The interface is handled by a separate standalone driver maintained in theALSA subsystem for simplicity. To minimize the interaction between the twosubsystems, a bridge is setup between the hdmi-lpe-audio and i915:1. Create a platform device to share MMIO/IRQ resources2. Make the platform device child of i915 device for runtime PM.3. Create IRQ chip to forward the LPE audio irqs.the hdmi-lpe-audio driver probes the lpe audio device and creates a newsound card

Threats:Due to the restriction in Linux platform device model, user need manuallyuninstall the hdmi-lpe-audio driver before uninstalling i915 module,otherwise we might run into use-after-free issues after i915 removes theplatform device: even though hdmi-lpe-audio driver is released, the modulesis still in “installed” status.

Implementation:The MMIO/REG platform resources are created according to the registersspecification.When forwarding LPE audio irqs, the flow control handler selection dependson the platform, for example on valleyview handle_simple_irq is enough.

voidintel_lpe_audio_irq_handler(structintel_display*display)¶

forwards the LPE audio irq

intintel_lpe_audio_init(structintel_display*display)¶

detect and setup the bridge between HDMI LPE Audio driver and i915

voidintel_lpe_audio_teardown(structintel_display*display)¶

destroy the bridge between HDMI LPE audio driver and i915

voidintel_lpe_audio_notify(structintel_display*display,enumtranscodercpu_transcoder,enumportport,constvoid*eld,intls_clock,booldp_output)¶

notify lpe audio event audio driver and i915

Panel Self Refresh PSR (PSR/SRD)¶

Since Haswell Display controller supports Panel Self-Refresh on displaypanels witch have a remote frame buffer (RFB) implemented according to PSRspec in eDP1.3. PSR feature allows the display to go to lower standby stateswhen system is idle but display is on as it eliminates display refreshrequest to DDR memory completely as long as the frame buffer for thatdisplay is unchanged.

Panel Self Refresh must be supported by both Hardware (source) andPanel (sink).

PSR saves power by caching the framebuffer in the panel RFB, which allows usto power down the link and memory controller. For DSI panels the same ideais called “manual mode”.

The implementation uses the hardware-based PSR support which automaticallyenters/exits self-refresh mode. The hardware takes care of sending therequired DP aux message and could even retrain the link (that part isn’tenabled yet though). The hardware also keeps track of any frontbufferchanges to know when to exit self-refresh mode again. Unfortunately thatpart doesn’t work too well, hence why the i915 PSR support uses thesoftware frontbuffer tracking to make sure it doesn’t miss a screenupdate. For this integrationintel_psr_invalidate() andintel_psr_flush()get called by the frontbuffer tracking code. Note that because of lockingissues the self-refresh re-enable code is done from a work queue, whichmust be correctly synchronized/cancelled when shutting down the pipe.”

DC3CO (DC3 clock off)

On top of PSR2, GEN12 adds a intermediate power savings state that turnsclock off automatically during PSR2 idle state.The smaller overhead of DC3co entry/exit vs. the overhead of PSR2 deep sleepentry/exit allows the HW to enter a low-power state even when page flippingperiodically (for instance a 30fps video playback scenario).

Every time a flips occurs PSR2 will get out of deep sleep state(if it was),so DC3CO is enabled and tgl_dc3co_disable_work is schedule to run after 6frames, if no other flip occurs and the function above is executed, DC3CO isdisabled and PSR2 is configured to enter deep sleep, resetting again in caseof another flip.Front buffer modifications do not trigger DC3CO activation on purpose as itwould bring a lot of complexity and most of the moderns systems will onlyuse page flips.

voidintel_psr_disable(structintel_dp*intel_dp,conststructintel_crtc_state*old_crtc_state)¶

Disable PSR

voidintel_psr_pause(structintel_dp*intel_dp)¶

Pause PSR

voidintel_psr_resume(structintel_dp*intel_dp)¶

Resume PSR

boolintel_psr_needs_vblank_notification(conststructintel_crtc_state*crtc_state)¶

Check if PSR need vblank enable/disable notification.

voidintel_psr_trigger_frame_change_event(structintel_dsb*dsb,structintel_atomic_state*state,structintel_crtc*crtc)¶

Trigger “Frame Change” event

intintel_psr_min_set_context_latency(conststructintel_crtc_state*crtc_state)¶

Minimum ‘set context latency’ lines needed by PSR

voidintel_psr_wait_for_idle_locked(conststructintel_crtc_state*new_crtc_state)¶

wait for PSR be ready for a pipe update

voidintel_psr_invalidate(structintel_display*display,unsignedfrontbuffer_bits,enumfb_op_originorigin)¶

Invalidate PSR

voidintel_psr_flush(structintel_display*display,unsignedfrontbuffer_bits,enumfb_op_originorigin)¶

Flush PSR

voidintel_psr_init(structintel_dp*intel_dp)¶

Init basic PSR work and mutex.

boolintel_psr_link_ok(structintel_dp*intel_dp)¶

return psr->link_ok

voidintel_psr_lock(conststructintel_crtc_state*crtc_state)¶

grab PSR lock

voidintel_psr_unlock(conststructintel_crtc_state*crtc_state)¶

release PSR lock

voidintel_psr_notify_dc5_dc6(structintel_display*display)¶

Notify PSR about enable/disable dc5/dc6

voidintel_psr_dc5_dc6_wa_init(structintel_display*display)¶

Init work for underrun on idle PSR HW bug wa

voidintel_psr_notify_pipe_change(structintel_atomic_state*state,structintel_crtc*crtc,boolenable)¶

Notify PSR about enable/disable of a pipe

voidintel_psr_notify_vblank_enable_disable(structintel_display*display,boolenable)¶

Notify PSR about enable/disable of vblank

Frame Buffer Compression (FBC)¶

FBC tries to save memory bandwidth (and so power consumption) bycompressing the amount of memory used by the display. It is totaltransparent to user space and completely handled in the kernel.

The benefits of FBC are mostly visible with solid backgrounds andvariation-less patterns. It comes from keeping the memory footprint smalland having fewer memory pages opened and accessed for refreshing the display.

i915 is responsible to reserve stolen memory for FBC and configure itsoffset on proper registers. The hardware takes care of allcompress/decompress. However there are many known cases where we have toforcibly disable it to allow proper screen updates.

voidintel_fbc_disable(structintel_crtc*crtc)¶

disable FBC if it’s associated with crtc

voidintel_fbc_handle_fifo_underrun_irq(structintel_display*display)¶

disable FBC when we get a FIFO underrun

voidintel_fbc_read_underrun_dbg_info(structintel_display*display,enumpipepipe,boollog)¶

Read and log FBC-related FIFO underrun debug info

voidintel_fbc_init(structintel_display*display)¶

Initialize FBC

voidintel_fbc_sanitize(structintel_display*display)¶

Sanitize FBC

Display Refresh Rate Switching (DRRS)¶

Display Refresh Rate Switching (DRRS) is a power conservation featurewhich enables swtching between low and high refresh rates,dynamically, based on the usage scenario. This feature is applicablefor internal panels.

Indication that the panel supports DRRS is given by the panel EDID, whichwould list multiple refresh rates for one resolution.

DRRS is of 2 types - static and seamless.Static DRRS involves changing refresh rate (RR) by doing a full modeset(may appear as a blink on screen) and is used in dock-undock scenario.Seamless DRRS involves changing RR without any visual effect to the userand can be used during normal system usage. This is done by programmingcertain registers.

Support for static/seamless DRRS may be indicated in the VBT based oninputs from the panel spec.

DRRS saves power by switching to low RR based on usage scenarios.

The implementation is based on frontbuffer tracking implementation. Whenthere is a disturbance on the screen triggered by user activity or a periodicsystem activity, DRRS is disabled (RR is changed to high RR). When there isno movement on screen, after a timeout of 1 second, a switch to low RR ismade.

For integration with frontbuffer tracking code,intel_drrs_invalidate()andintel_drrs_flush() are called.

DRRS can be further extended to support other internal panels and alsothe scenario of video playback wherein RR is set based on the raterequested by userspace.

voidintel_drrs_activate(conststructintel_crtc_state*crtc_state)¶

activate DRRS

voidintel_drrs_deactivate(conststructintel_crtc_state*old_crtc_state)¶

deactivate DRRS

voidintel_drrs_invalidate(structintel_display*display,unsignedintfrontbuffer_bits)¶

Disable Idleness DRRS

voidintel_drrs_flush(structintel_display*display,unsignedintfrontbuffer_bits)¶

Restart Idleness DRRS

voidintel_drrs_crtc_init(structintel_crtc*crtc)¶

Init DRRS for CRTC

DPIO¶

VLV, CHV and BXT have slightly peculiar display PHYs for driving DP/HDMIports. DPIO is the name given to such a display PHY. These PHYsdon’t follow the standard programming model using direct MMIOregisters, and instead their registers must be accessed through IOSFsideband. VLV has one such PHY for driving ports B and C, and CHVadds another PHY for driving port D. Each PHY responds to specificIOSF-SB port.

Each display PHY is made up of one or two channels. Each channelhouses a common lane part which contains the PLL and other commonlogic. CH0 common lane also contains the IOSF-SB logic for theCommon Register Interface (CRI) ie. the DPIO registers. CRI clockmust be running when any DPIO registers are accessed.

In addition to having their own registers, the PHYs are alsocontrolled through some dedicated signals from the displaycontroller. These include PLL reference clock enable, PLL enable,and CRI clock selection, for example.

Eeach channel also has two splines (also called data lanes), andeach spline is made up of one Physical Access Coding Sub-Layer(PCS) block and two TX lanes. So each channel has two PCS blocksand four TX lanes. The TX lanes are used as DP lanes or TMDSdata/clock pairs depending on the output type.

Additionally the PHY also contains an AUX lane with AUX blocksfor each channel. This is used for DP AUX communication, butthis fact isn’t really relevant for the driver since AUX iscontrolled from the display controller side. No DPIO registersneed to be accessed during AUX communication,

Generally on VLV/CHV the common lane corresponds to the pipe andthe spline (PCS/TX) corresponds to the port.

For dual channel PHY (VLV/CHV):

pipe A == CMN/PLL/REF CH0

pipe B == CMN/PLL/REF CH1

port B == PCS/TX CH0

port C == PCS/TX CH1

This is especially important when we cross the streamsie. drive port B with pipe B, or port C with pipe A.

For single channel PHY (CHV):

pipe C == CMN/PLL/REF CH0

port D == PCS/TX CH0

On BXT the entire PHY channel corresponds to the port. That meansthe PLL is also now associated with the port rather than the pipe,and so the clock needs to be routed to the appropriate transcoder.Port A PLL is directly connected to transcoder EDP and port B/CPLLs can be routed to any transcoder A/B/C.

Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 isdigital port D (CHV) or port A (BXT).

Dual channel PHY (VLV/CHV/BXT)---------------------------------|      CH0      |      CH1      ||  CMN/PLL/REF  |  CMN/PLL/REF  ||---------------|---------------| Display PHY| PCS01 | PCS23 | PCS01 | PCS23 ||-------|-------|-------|-------||TX0|TX1|TX2|TX3|TX0|TX1|TX2|TX3|---------------------------------|     DDI0      |     DDI1      | DP/HDMI ports---------------------------------Single channel PHY (CHV/BXT)-----------------|      CH0      ||  CMN/PLL/REF  ||---------------| Display PHY| PCS01 | PCS23 ||-------|-------||TX0|TX1|TX2|TX3|-----------------|     DDI2      | DP/HDMI port-----------------

DMC Firmware Support¶

From gen9 onwards we have newly added DMC (Display microcontroller) in displayengine to save and restore the state of display engine when it enter intolow-power state and comes back to normal.

voidintel_dmc_block_pkgc(structintel_display*display,enumpipepipe,boolblock)¶

block PKG C-state

voidintel_dmc_start_pkgc_exit_at_start_of_undelayed_vblank(structintel_display*display,enumpipepipe,boolenable)¶

start of PKG C-state exit

voidintel_dmc_load_program(structintel_display*display)¶

write the firmware from memory to register.

voidintel_dmc_disable_program(structintel_display*display)¶

disable the firmware

voidintel_dmc_init(structintel_display*display)¶

initialize the firmware loading.

voidintel_dmc_suspend(structintel_display*display)¶

prepare DMC firmware before system suspend

voidintel_dmc_resume(structintel_display*display)¶

init DMC firmware during system resume

voidintel_dmc_fini(structintel_display*display)¶

unload the DMC firmware.

DMC Flip Queue¶

A flip queue is a ring buffer implemented by the pipe DMC firmware.The driver inserts entries into the queues to be executed by thepipe DMC at a specified presentation timestamp (PTS).

Each pipe DMC provides several queues:

• 1 general queue (two DSB buffers executed per entry)

• 3 plane queues (one DSB buffer executed per entry)

• 1 fast queue (deprecated)

DMC wakelock support¶

Wake lock is the mechanism to cause display engine to exit DCstates to allow programming to registers that are powered down inthose states. Previous projects exited DC states automatically whendetecting programming. Now software controls the exit byprogramming the wake lock. This improves system performance andsystem interactions and better fits the flip queue style ofprogramming. Wake lock is only required when DC5, DC6, or DC6v havebeen enabled in DC_STATE_EN and the wake lock mode of operation hasbeen enabled.

The wakelock mechanism in DMC allows the display engine to exit DCstates explicitly before programming registers that may be powereddown. In earlier hardware, this was done automatically andimplicitly when the display engine accessed a register. With thewakelock implementation, the driver asserts a wakelock in DMC,which forces it to exit the DC state until the wakelock isdeasserted.

The mechanism can be enabled and disabled by writing to theDMC_WAKELOCK_CFG register. There are also 13 control registersthat can be used to hold and release different wakelocks. In thecurrent implementation, we only need one wakelock, so onlyDMC_WAKELOCK1_CTL is used. The other definitions are here forpotential future use.

Video BIOS Table (VBT)¶

The Video BIOS Table, or VBT, provides platform and board specificconfiguration information to the driver that is not discoverable or availablethrough other means. The configuration is mostly related to displayhardware. The VBT is available via the ACPI OpRegion or, on older systems, inthe PCI ROM.

The VBT consists of a VBT Header (defined asstructvbt_header), a BDBHeader (structbdb_header), and a number of BIOS Data Blocks (BDB) thatcontain the actual configuration information. The VBT Header, and thus theVBT, begins with “$VBT” signature. The VBT Header contains the offset of theBDB Header. The data blocks are concatenated after the BDB Header. The datablocks have a 1-byte Block ID, 2-byte Block Size, and Block Size bytes ofdata. (Block 53, the MIPI Sequence Block is an exception.)

The driver parses the VBT during load. The relevant information is stored indriver private data for ease of use, and the actual VBT is not read afterthat.

boolintel_bios_is_valid_vbt(structintel_display*display,constvoid*buf,size_tsize)¶

does the given buffer contain a valid VBT

voidintel_bios_init(structintel_display*display)¶

find VBT and initialize settings from the BIOS

voidintel_bios_driver_remove(structintel_display*display)¶

Free any resources allocated byintel_bios_init()

boolintel_bios_is_tv_present(structintel_display*display)¶

is integrated TV present in VBT

boolintel_bios_is_lvds_present(structintel_display*display,u8*i2c_pin)¶

is LVDS present in VBT

boolintel_bios_is_port_present(structintel_display*display,enumportport)¶

is the specified digital port present

boolintel_bios_is_dsi_present(structintel_display*display,enumport*port)¶

is DSI present in VBT

structvbt_header¶

VBT Header structure

struct vbt_header {    u8 signature[20];    u16 version;    u16 header_size;    u16 vbt_size;    u8 vbt_checksum;    u8 reserved0;    u32 bdb_offset;    u32 aim_offset[4];};

structbdb_header¶

BDB Header structure

struct bdb_header {    u8 signature[16];    u16 version;    u16 header_size;    u16 bdb_size;};

Display clocks¶

The display engine uses several different clocks to do its work. Thereare two main clocks involved that aren’t directly related to the actualpixel clock or any symbol/bit clock of the actual output port. Theseare the core display clock (CDCLK) and RAWCLK.

CDCLK clocks most of the display pipe logic, and thus its frequencymust be high enough to support the rate at which pixels are flowingthrough the pipes. Downscaling must also be accounted as that increasesthe effective pixel rate.

On several platforms the CDCLK frequency can be changed dynamicallyto minimize power consumption for a given display configuration.Typically changes to the CDCLK frequency require all the display pipesto be shut down while the frequency is being changed.

On SKL+ the DMC will toggle the CDCLK off/on during DC5/6 entry/exit.DMC will not change the active CDCLK frequency however, so that partwill still be performed by the driver directly.

There are multiple components involved in the generation of the CDCLKfrequency:

• We have the CDCLK PLL, which generates an output clock based on areference clock and a ratio parameter.

• The CD2X Divider, which divides the output of the PLL based on adivisor selected from a set of pre-defined choices.

• The CD2X Squasher, which further divides the output based on awaveform represented as a sequence of bits where each zero“squashes out” a clock cycle.

• And, finally, a fixed divider that divides the output frequency by 2.

As such, the resulting CDCLK frequency can be calculated with thefollowing formula:

cdclk = vco / cd2x_div / (sq_len / sq_div) / 2

, where vco is the frequency generated by the PLL; cd2x_divrepresents the CD2X Divider; sq_len and sq_div are the bit lengthand the number of high bits for the CD2X Squasher waveform, respectively;and 2 represents the fixed divider.

Note that some older platforms do not contain the CD2X Dividerand/or CD2X Squasher, in which case we can ignore their respectivefactors in the formula above.

Several methods exist to change the CDCLK frequency, which ones aresupported depends on the platform:

• Full PLL disable + re-enable with new VCO frequency. Pipes must be inactive.

• CD2X divider update. Single pipe can be active as the divider updatecan be synchronized with the pipe’s start of vblank.

• Crawl the PLL smoothly to the new VCO frequency. Pipes can be active.

• Squash waveform update. Pipes can be active.

• Crawl and squash can also be done back to back. Pipes can be active.

RAWCLK is a fixed frequency clock, often used by various auxiliaryblocks such as AUX CH or backlight PWM. Hence the only thing wereally need to know about RAWCLK is its frequency so that variousdividers can be programmed correctly.

voidintel_cdclk_init_hw(structintel_display*display)¶

Initialize CDCLK hardware

voidintel_cdclk_uninit_hw(structintel_display*display)¶

Uninitialize CDCLK hardware

boolintel_cdclk_clock_changed(conststructintel_cdclk_config*a,conststructintel_cdclk_config*b)¶

Check whether the clock changed

boolintel_cdclk_can_cd2x_update(structintel_display*display,conststructintel_cdclk_config*a,conststructintel_cdclk_config*b)¶

Determine if changing between the two CDCLK configurations requires only a cd2x divider update

boolintel_cdclk_changed(conststructintel_cdclk_config*a,conststructintel_cdclk_config*b)¶

Determine if two CDCLK configurations are different

voidintel_set_cdclk_pre_plane_update(structintel_atomic_state*state)¶

Push the CDCLK state to the hardware

voidintel_set_cdclk_post_plane_update(structintel_atomic_state*state)¶

Push the CDCLK state to the hardware

voidintel_update_max_cdclk(structintel_display*display)¶

Determine the maximum support CDCLK frequency

voidintel_update_cdclk(structintel_display*display)¶

Determine the current CDCLK frequency

u32intel_read_rawclk(structintel_display*display)¶

Determine the current RAWCLK frequency

voidintel_init_cdclk_hooks(structintel_display*display)¶

Initialize CDCLK related modesetting hooks

Display PLLs¶

Display PLLs used for driving outputs vary by platform. While some haveper-pipe or per-encoder dedicated PLLs, others allow the use of any PLLfrom a pool. In the latter scenario, it is possible that multiple pipesshare a PLL if their configurations match.

This file provides an abstraction over display PLLs. The functionintel_dpll_init() initializes the PLLs for the given platform. Theusers of a PLL are tracked and that tracking is integrated with the atomicmodset interface. During an atomic operation, required PLLs can be reservedfor a given CRTC and encoder configuration by callingintel_dpll_reserve() and previously reserved PLLs can be releasedwithintel_dpll_release().Changes to the users are first staged in the atomic state, and then madeeffective by callingintel_dpll_swap_state() during the atomiccommit phase.

structintel_dpll*intel_get_dpll_by_id(structintel_display*display,enumintel_dpll_idid)¶

get a DPLL given its id

voidintel_dpll_enable(conststructintel_crtc_state*crtc_state)¶

enable a CRTC’s DPLL

voidintel_dpll_disable(conststructintel_crtc_state*crtc_state)¶

disable a CRTC’s shared DPLL

voidintel_dpll_crtc_get(conststructintel_crtc*crtc,conststructintel_dpll*pll,structintel_dpll_state*dpll_state)¶

Get a DPLL reference for a CRTC

voidintel_dpll_crtc_put(conststructintel_crtc*crtc,conststructintel_dpll*pll,structintel_dpll_state*dpll_state)¶

Drop a DPLL reference for a CRTC

voidintel_dpll_swap_state(structintel_atomic_state*state)¶

make atomic DPLL configuration effective

voidicl_set_active_port_dpll(structintel_crtc_state*crtc_state,enumicl_port_dpll_idport_dpll_id)¶

select the active port DPLL for a given CRTC

voidintel_dpll_init(structintel_display*display)¶

Initialize DPLLs

intintel_dpll_compute(structintel_atomic_state*state,structintel_crtc*crtc,structintel_encoder*encoder)¶

compute DPLL state CRTC and encoder combination

intintel_dpll_reserve(structintel_atomic_state*state,structintel_crtc*crtc,structintel_encoder*encoder)¶

reserve DPLLs for CRTC and encoder combination

voidintel_dpll_release(structintel_atomic_state*state,structintel_crtc*crtc)¶

end use of DPLLs by CRTC in atomic state

voidintel_dpll_update_active(structintel_atomic_state*state,structintel_crtc*crtc,structintel_encoder*encoder)¶

update the active DPLL for a CRTC/encoder

intintel_dpll_get_freq(structintel_display*display,conststructintel_dpll*pll,conststructintel_dpll_hw_state*dpll_hw_state)¶

calculate the DPLL’s output frequency

boolintel_dpll_get_hw_state(structintel_display*display,structintel_dpll*pll,structintel_dpll_hw_state*dpll_hw_state)¶

readout the DPLL’s hardware state

voidintel_dpll_dump_hw_state(structintel_display*display,structdrm_printer*p,conststructintel_dpll_hw_state*dpll_hw_state)¶

dump hw_state

boolintel_dpll_compare_hw_state(structintel_display*display,conststructintel_dpll_hw_state*a,conststructintel_dpll_hw_state*b)¶

compare the two states

enumintel_dpll_id¶

possible DPLL ids

Description

Enumeration of possible IDs for a DPLL. Real shared dpll ids must be >= 0.

structintel_dpll_state¶

hold the DPLL atomic state

struct intel_dpll_state {    u8 pipe_mask;    struct intel_dpll_hw_state hw_state;};

Description

This structure holds an atomic state for the DPLL, that can representeither its current state (in structintel_shared_dpll) or a desiredfuture state which would be applied by an atomic mode set (stored ina structintel_atomic_state).

See alsointel_reserve_shared_dplls() andintel_release_shared_dplls().

structdpll_info¶

display PLL platform specific info

struct dpll_info {    const char *name;    const struct intel_dpll_funcs *funcs;    enum intel_dpll_id id;    enum intel_display_power_domain power_domain;    bool always_on;    bool is_alt_port_dpll;};

structintel_dpll¶

display PLL with tracked state and users

struct intel_dpll {    struct intel_dpll_state state;    u8 index;    u8 active_mask;    bool on;    const struct dpll_info *info;    struct ref_tracker *wakeref;};

Display State Buffer¶

A DSB (Display State Buffer) is a queue of MMIO instructions in the memorywhich can be offloaded to DSB HW in Display Controller. DSB HW is a DMAengine that can be programmed to download the DSB from memory.It allows driver to batch submit display HW programming. This helps toreduce loading time and CPU activity, thereby making the context switchfaster. DSB Support added from Gen12 Intel graphics based platform.

DSB’s can access only the pipe, plane, and transcoder Data Island Packetregisters.

DSB HW can support only register writes (both indexed and direct MMIOwrites). There are no registers reads possible with DSB HW engine.

voidintel_dsb_reg_write_indexed(structintel_dsb*dsb,i915_reg_treg,u32val)¶

Emit indexed register write to the DSB context

voidintel_dsb_commit(structintel_dsb*dsb)¶

Trigger workload execution of DSB.

structintel_dsb*intel_dsb_prepare(structintel_atomic_state*state,structintel_crtc*crtc,enumintel_dsb_iddsb_id,unsignedintmax_cmds)¶

Allocate, pin and map the DSB command buffer.