Managing Ownership of the Framebuffer Aperture¶

A graphics device might be supported by different drivers, but only onedriver can be active at any given time. Many systems load a genericgraphics drivers, such as EFI-GOP or VESA, early during the boot process.During later boot stages, they replace the generic driver with a dedicated,hardware-specific driver. To take over the device, the dedicated driverfirst has to remove the generic driver. Aperture functions manageownership of framebuffer memory and hand-over between drivers.

Graphics drivers should callaperture_remove_conflicting_devices()at the top of their probe function. The function removes any genericdriver that is currently associated with the given framebuffer memory.An example for a graphics device on the platform bus is shown below.

staticintexample_probe(structplatform_device*pdev){structresource*mem;resource_size_tbase,size;intret;mem=platform_get_resource(pdev,IORESOURCE_MEM,0);if(!mem)return-ENODEV;base=mem->start;size=resource_size(mem);ret=aperture_remove_conflicting_devices(base,size,"example");if(ret)returnret;// Initialize the hardware...return0;}staticconststructplatform_driverexample_driver={.probe=example_probe,...};

The given example reads the platform device’s I/O-memory range from thedevice instance. An active framebuffer will be located within this range.The call toaperture_remove_conflicting_devices() releases drivers thathave previously claimed ownership of the range and are currently drivingoutput on the framebuffer. If successful, the new driver can take overthe device.

While the given example uses a platform device, the aperture helpers workwith every bus that has an addressable framebuffer. In the case of PCI,device drivers can also callaperture_remove_conflicting_pci_devices() andlet the function detect the apertures automatically. Device drivers withoutknowledge of the framebuffer’s location can callaperture_remove_all_conflicting_devices(), which removes all known devices.

Drivers that are susceptible to being removed by other drivers, such asgeneric EFI or VESA drivers, have to register themselves as owners of theirframebuffer apertures. Ownership of the framebuffer memory is achievedby callingdevm_aperture_acquire_for_platform_device(). If successful, thedriver is the owner of the framebuffer range. The function fails if theframebuffer is already owned by another driver. See below for an example.

staticintgeneric_probe(structplatform_device*pdev){structresource*mem;resource_size_tbase,size;mem=platform_get_resource(pdev,IORESOURCE_MEM,0);if(!mem)return-ENODEV;base=mem->start;size=resource_size(mem);ret=devm_aperture_acquire_for_platform_device(pdev,base,size);if(ret)returnret;// Initialize the hardware...return0;}staticintgeneric_remove(structplatform_device*){// Hot-unplug the device...return0;}staticconststructplatform_drivergeneric_driver={.probe=generic_probe,.remove=generic_remove,...};

The similar to the previous example, the generic driver claims ownershipof the framebuffer memory from its probe function. This will fail if thememory range, or parts of it, is already owned by another driver.

If successful, the generic driver is now subject to forced removal byanother driver. This only works for platform drivers that support hotunplugging. When a driver callsaperture_remove_conflicting_devices()et al for the registered framebuffer range, the aperture helpers callplatform_device_unregister() and the generic driver unloads itself. Thegeneric driver also has to provide a remove function to make this work.Once hot unplugged from hardware, it may not access the device’sregisters, framebuffer memory, ROM, etc afterwards.

intaperture_remove_all_conflicting_devices(constchar*name)¶

remove all existing framebuffers

intdevm_aperture_acquire_for_platform_device(structplatform_device*pdev,resource_size_tbase,resource_size_tsize)¶

Acquires ownership of an aperture on behalf of a platform device.

intaperture_remove_conflicting_devices(resource_size_tbase,resource_size_tsize,constchar*name)¶

remove devices in the given range

int__aperture_remove_legacy_vga_devices(structpci_dev*pdev)¶

remove legacy VGA devices of a PCI devices

intaperture_remove_conflicting_pci_devices(structpci_dev*pdev,constchar*name)¶

remove existing framebuffers for PCI devices