DC Programming Model¶
In theDisplay Core Next (DCN) andDCN Block pages, you learned about the hardware components and how theyinteract with each other. On this page, the focus is shifted to the displaycode architecture. Hence, it is reasonable to remind the reader that the codein DC is shared with other OSes; for this reason, DC provides a set ofabstractions and operations to connect different APIs with the hardwareconfiguration. See DC as a service available for a Display Manager (amdgpu_dm)to access and configure DCN/DCE hardware (DCE is also part of DC, but forsimplicity’s sake, this documentation only examines DCN).
Note
For this page, we will use the term GPU to refers to dGPU and APU.
Overview¶
From the display hardware perspective, it is plausible to expect that if aproblem is well-defined, it will probably be implemented at the hardware level.On the other hand, when there are multiple ways of achieving something withouta very well-defined scope, the solution is usually implemented as a policy atthe DC level. In other words, some policies are defined in the DC core(resource management, power optimization, image quality, etc.), and the othersimplemented in hardware are enabled via DC configuration.
In terms of hardware management, DCN has multiple instances of the same block(e.g., HUBP, DPP, MPC, etc), and during the driver execution, it might benecessary to use some of these instances. The core has policies in place forhandling those instances. Regarding resource management, the DC objective isquite simple: minimize the hardware shuffle when the driver performs someactions. When the state changes from A to B, the transition is consideredeasier to maneuver if the hardware resource is still used for the same set ofdriver objects. Usually, adding and removing a resource to apipe_ctx (moredetails below) is not a problem; however, moving a resource from onepipe_ctxto another should be avoided.
Another area of influence for DC is power optimization, which has a myriad ofarrangement possibilities. In some way, just displaying an image via DCN shouldbe relatively straightforward; however, showing it with the best powerfootprint is more desirable, but it has many associated challenges.Unfortunately, there is no straight-forward analytic way to determine if aconfiguration is the best one for the context due to the enormous variety ofvariables related to this problem (e.g., many different DCN/DCE hardwareversions, different displays configurations, etc.) for this reason DCimplements a dedicated library for trying some configuration and verify if itis possible to support it or not. This type of policy is extremely complex tocreate and maintain, and amdgpu driver relies on Display Mode Library (DML) togenerate the best decisions.
In summary, DC must deal with the complexity of handling multiple scenarios anddetermine policies to manage them. All of the above information is conveyed togive the reader some idea about the complexity of driving a display from thedriver’s perspective. This page hopes to allow the reader to better navigateover the amdgpu display code.
Display Driver Architecture Overview¶
The diagram below provides an overview of the display driver architecture;notice it illustrates the software layers adopted by DC:
The first layer of the diagram is the high-level DC API represented by thedc.h file; below it are two big blocks represented by Core and Link. Next isthe hardware configuration block; the main file describing it isthe`hw_sequencer.h`, where the implementation of the callbacks can be found inthe hardware sequencer folder. Almost at the end, you can see the block levelAPI (dc/inc/hw), which represents each DCN low-level block, such as HUBP,DPP, MPC, OPTC, etc. Notice on the left side of the diagram that we have adifferent set of layers representing the interaction with the DMUBmicrocontroller.
Basic Objects¶
The below diagram outlines the basic display objects. In particular, payattention to the names in the boxes since they represent a data structure inthe driver:
Let’s start with the central block in the image,dc. Thedcstructisinitialized per GPU; for example, one GPU has onedc instance, two GPUs havetwodc instances, and so forth. In other words we have one ‘dc’ per ‘amdgpu’instance. In some ways, this object behaves like theSingleton pattern.
After thedc block in the diagram, you can see thedc_link component, whichis a low-level abstraction for the connector. One interesting aspect of theimage is that connectors are not part of the DCN block; they are defined by theplatform/board and not by the SoC. Thedc_linkstructis the high-level datacontainer with information such as connected sinks, connection status, signaltypes, etc. Afterdc_link, there is thedc_sink, which is the object thatrepresents the connected display.
Note
For historical reasons, we used the namedc_link, which gives thewrong impression that this abstraction only deals with physical connectionsthat the developer can easily manipulate. However, this also coversconnections like eDP or cases where the output is connected to other devices.
There are two structs that are not represented in the diagram since they wereelaborated in the DCN overview page (check the DCN block diagramDisplayCore Next (DCN)); still, it is worth bringing back for thisoverview which isdc_stream anddc_state. Thedc_stream stores manyproperties associated with the data transmission, but most importantly, itrepresents the data flow from the connector to the display. Next we havedc_state, which represents the logic state within the hardware at the moment;dc_state is composed ofdc_stream anddc_plane. Thedc_stream is the DCversion ofdrm_crtc and represents the post-blending pipeline.
Speaking of thedc_plane data structure (first part of the diagram), you canthink about it as an abstraction similar todrm_plane that represents thepre-blending portion of the pipeline. This image was probably processed by GFXand is ready to be composited under adc_stream. Normally, the driver mayhave one or moredc_plane connected to the samedc_stream, which defines acomposition at the DC level.
Basic Operations¶
Now that we have covered the basic objects, it is time to examine some of thebasic hardware/software operations. Let’s start with thedc_create()function, which directly works with thedc data struct; this function behaveslike a constructor responsible for the basic software initialization andpreparing for enabling other parts of the API. It is important to highlightthat this operation does not touch any hardware configuration; it is only asoftware initialization.
Next, we have thedc_hardware_init(), which also relies on thedc datastruct. Its main function is to put the hardware in a valid state. It is worthhighlighting that the hardware might initialize in an unknown state, and it isa requirement to put it in a valid state; this function has multiple callbacksfor the hardware-specific initialization, whereasdc_hardware_init does thehardware initialization and is the first point where we touch hardware.
Thedc_get_link_at_index is an operation that depends on thedc_link datastructure. This function retrieves and enumerates all thedc_links availableon the device; this is required since this information is not part of the SoCdefinition but depends on the board configuration. As soon as thedc_link isinitialized, it is useful to figure out if any of them are already connected tothe display by using thedc_link_detect() function. After the driver figuresout if any display is connected to the device, the challenging phase starts:configuring the monitor to show something. Nonetheless, dealing with the idealconfiguration is not a DC task since this is the Display Manager (amdgpu_dm)responsibility which in turn is responsible for dealing with the atomiccommits. The only interface DC provides to the configuration phase is thefunctiondc_validate_with_context that receives the configuration informationand, based on that, validates whether the hardware can support it or not. It isimportant to add that even if the display supports some specific configuration,it does not mean the DCN hardware can support it.
After the DM and DC agree upon the configuration, the stream configurationphase starts. This task activates one or moredc_stream at this phase, and inthe best-case scenario, you might be able to turn the display on with a blackscreen (it does not show anything yet since it does not have any planeassociated with it). The final step would be to call thedc_update_planes_and_stream, which will add or remove planes.