drivers/video/aperture.c

   1 // SPDX-License-Identifier: MIT
   2
   3 #include <linux/aperture.h>
   4 #include <linux/device.h>
   5 #include <linux/fb.h> /* for old fbdev helpers */
   6 #include <linux/list.h>
   7 #include <linux/mutex.h>
   8 #include <linux/pci.h>
   9 #include <linux/platform_device.h>
  10 #include <linux/slab.h>
  11 #include <linux/sysfb.h>
  12 #include <linux/types.h>
  13 #include <linux/vgaarb.h>
  14
  15 #include <video/vga.h>
  16
  17 /**
  18  * DOC: overview
  19  *
  20  * A graphics device might be supported by different drivers, but only one
  21  * driver can be active at any given time. Many systems load a generic
  22  * graphics drivers, such as EFI-GOP or VESA, early during the boot process.
  23  * During later boot stages, they replace the generic driver with a dedicated,
  24  * hardware-specific driver. To take over the device the dedicated driver
  25  * first has to remove the generic driver. Aperture functions manage
  26  * ownership of framebuffer memory and hand-over between drivers.
  27  *
  28  * Graphics drivers should call aperture_remove_conflicting_devices()
  29  * at the top of their probe function. The function removes any generic
  30  * driver that is currently associated with the given framebuffer memory.
  31  * An example for a graphics device on the platform bus is shown below.
  32  *
  33  * .. code-block:: c
  34  *
  35  *      static int example_probe(struct platform_device *pdev)
  36  *      {
  37  *              struct resource *mem;
  38  *              resource_size_t base, size;
  39  *              int ret;
  40  *
  41  *              mem = platform_get_resource(pdev, IORESOURCE_MEM, 0);
  42  *              if (!mem)
  43  *                      return -ENODEV;
  44  *              base = mem->start;
  45  *              size = resource_size(mem);
  46  *
  47  *              ret = aperture_remove_conflicting_devices(base, size, false, "example");
  48  *              if (ret)
  49  *                      return ret;
  50  *
  51  *              // Initialize the hardware
  52  *              ...
  53  *
  54  *              return 0;
  55  *      }
  56  *
  57  *      static const struct platform_driver example_driver = {
  58  *              .probe = example_probe,
  59  *              ...
  60  *      };
  61  *
  62  * The given example reads the platform device's I/O-memory range from the
  63  * device instance. An active framebuffer will be located within this range.
  64  * The call to aperture_remove_conflicting_devices() releases drivers that
  65  * have previously claimed ownership of the range and are currently driving
  66  * output on the framebuffer. If successful, the new driver can take over
  67  * the device.
  68  *
  69  * While the given example uses a platform device, the aperture helpers work
  70  * with every bus that has an addressable framebuffer. In the case of PCI,
  71  * device drivers can also call aperture_remove_conflicting_pci_devices() and
  72  * let the function detect the apertures automatically. Device drivers without
  73  * knowledge of the framebuffer's location can call
  74  * aperture_remove_all_conflicting_devices(), which removes all known devices.
  75  *
  76  * Drivers that are susceptible to being removed by other drivers, such as
  77  * generic EFI or VESA drivers, have to register themselves as owners of their
  78  * framebuffer apertures. Ownership of the framebuffer memory is achieved
  79  * by calling devm_aperture_acquire_for_platform_device(). If successful, the
  80  * driveris the owner of the framebuffer range. The function fails if the
  81  * framebuffer is already owned by another driver. See below for an example.
  82  *
  83  * .. code-block:: c
  84  *
  85  *      static int generic_probe(struct platform_device *pdev)
  86  *      {
  87  *              struct resource *mem;
  88  *              resource_size_t base, size;
  89  *
  90  *              mem = platform_get_resource(pdev, IORESOURCE_MEM, 0);
  91  *              if (!mem)
  92  *                      return -ENODEV;
  93  *              base = mem->start;
  94  *              size = resource_size(mem);
  95  *
  96  *              ret = devm_aperture_acquire_for_platform_device(pdev, base, size);
  97  *              if (ret)
  98  *                      return ret;
  99  *
 100  *              // Initialize the hardware
 101  *              ...
 102  *
 103  *              return 0;
 104  *      }
 105  *
 106  *      static int generic_remove(struct platform_device *)
 107  *      {
 108  *              // Hot-unplug the device
 109  *              ...
 110  *
 111  *              return 0;
 112  *      }
 113  *
 114  *      static const struct platform_driver generic_driver = {
 115  *              .probe = generic_probe,
 116  *              .remove = generic_remove,
 117  *              ...
 118  *      };
 119  *
 120  * The similar to the previous example, the generic driver claims ownership
 121  * of the framebuffer memory from its probe function. This will fail if the
 122  * memory range, or parts of it, is already owned by another driver.
 123  *
 124  * If successful, the generic driver is now subject to forced removal by
 125  * another driver. This only works for platform drivers that support hot
 126  * unplugging. When a driver calls aperture_remove_conflicting_devices()
 127  * et al for the registered framebuffer range, the aperture helpers call
 128  * platform_device_unregister() and the generic driver unloads itself. The
 129  * generic driver also has to provide a remove function to make this work.
 130  * Once hot unplugged fro mhardware, it may not access the device's
 131  * registers, framebuffer memory, ROM, etc afterwards.
 132  */
 133
 134 struct aperture_range {
 135         struct device *dev;
 136         resource_size_t base;
 137         resource_size_t size;
 138         struct list_head lh;
 139         void (*detach)(struct device *dev);
 140 };
 141
 142 static LIST_HEAD(apertures);
 143 static DEFINE_MUTEX(apertures_lock);
 144
 145 static bool overlap(resource_size_t base1, resource_size_t end1,
 146                     resource_size_t base2, resource_size_t end2)
 147 {
 148         return (base1 < end2) && (end1 > base2);
 149 }
 150
 151 static void devm_aperture_acquire_release(void *data)
 152 {
 153         struct aperture_range *ap = data;
 154         bool detached = !ap->dev;
 155
 156         if (detached)
 157                 return;
 158
 159         mutex_lock(&apertures_lock);
 160         list_del(&ap->lh);
 161         mutex_unlock(&apertures_lock);
 162 }
 163
 164 static int devm_aperture_acquire(struct device *dev,
 165                                  resource_size_t base, resource_size_t size,
 166                                  void (*detach)(struct device *))
 167 {
 168         size_t end = base + size;
 169         struct list_head *pos;
 170         struct aperture_range *ap;
 171
 172         mutex_lock(&apertures_lock);
 173
 174         list_for_each(pos, &apertures) {
 175                 ap = container_of(pos, struct aperture_range, lh);
 176                 if (overlap(base, end, ap->base, ap->base + ap->size)) {
 177                         mutex_unlock(&apertures_lock);
 178                         return -EBUSY;
 179                 }
 180         }
 181
 182         ap = devm_kzalloc(dev, sizeof(*ap), GFP_KERNEL);
 183         if (!ap) {
 184                 mutex_unlock(&apertures_lock);
 185                 return -ENOMEM;
 186         }
 187
 188         ap->dev = dev;
 189         ap->base = base;
 190         ap->size = size;
 191         ap->detach = detach;
 192         INIT_LIST_HEAD(&ap->lh);
 193
 194         list_add(&ap->lh, &apertures);
 195
 196         mutex_unlock(&apertures_lock);
 197
 198         return devm_add_action_or_reset(dev, devm_aperture_acquire_release, ap);
 199 }
 200
 201 static void aperture_detach_platform_device(struct device *dev)
 202 {
 203         struct platform_device *pdev = to_platform_device(dev);
 204
 205         /*
 206          * Remove the device from the device hierarchy. This is the right thing
 207          * to do for firmware-based DRM drivers, such as EFI, VESA or VGA. After
 208          * the new driver takes over the hardware, the firmware device's state
 209          * will be lost.
 210          *
 211          * For non-platform devices, a new callback would be required.
 212          *
 213          * If the aperture helpers ever need to handle native drivers, this call
 214          * would only have to unplug the DRM device, so that the hardware device
 215          * stays around after detachment.
 216          */
 217         platform_device_unregister(pdev);
 218 }
 219
 220 /**
 221  * devm_aperture_acquire_for_platform_device - Acquires ownership of an aperture
 222  *                                             on behalf of a platform device.
 223  * @pdev:       the platform device to own the aperture
 224  * @base:       the aperture's byte offset in physical memory
 225  * @size:       the aperture size in bytes
 226  *
 227  * Installs the given device as the new owner of the aperture. The function
 228  * expects the aperture to be provided by a platform device. If another
 229  * driver takes over ownership of the aperture, aperture helpers will then
 230  * unregister the platform device automatically. All acquired apertures are
 231  * released automatically when the underlying device goes away.
 232  *
 233  * The function fails if the aperture, or parts of it, is currently
 234  * owned by another device. To evict current owners, callers should use
 235  * remove_conflicting_devices() et al. before calling this function.
 236  *
 237  * Returns:
 238  * 0 on success, or a negative errno value otherwise.
 239  */
 240 int devm_aperture_acquire_for_platform_device(struct platform_device *pdev,
 241                                               resource_size_t base,
 242                                               resource_size_t size)
 243 {
 244         return devm_aperture_acquire(&pdev->dev, base, size, aperture_detach_platform_device);
 245 }
 246 EXPORT_SYMBOL(devm_aperture_acquire_for_platform_device);
 247
 248 static void aperture_detach_devices(resource_size_t base, resource_size_t size)
 249 {
 250         resource_size_t end = base + size;
 251         struct list_head *pos, *n;
 252
 253         mutex_lock(&apertures_lock);
 254
 255         list_for_each_safe(pos, n, &apertures) {
 256                 struct aperture_range *ap = container_of(pos, struct aperture_range, lh);
 257                 struct device *dev = ap->dev;
 258
 259                 if (WARN_ON_ONCE(!dev))
 260                         continue;
 261
 262                 if (!overlap(base, end, ap->base, ap->base + ap->size))
 263                         continue;
 264
 265                 ap->dev = NULL; /* detach from device */
 266                 list_del(&ap->lh);
 267
 268                 ap->detach(dev);
 269         }
 270
 271         mutex_unlock(&apertures_lock);
 272 }
 273
 274 /**
 275  * aperture_remove_conflicting_devices - remove devices in the given range
 276  * @base: the aperture's base address in physical memory
 277  * @size: aperture size in bytes
 278  * @primary: also kick vga16fb if present; only relevant for VGA devices
 279  * @name: a descriptive name of the requesting driver
 280  *
 281  * This function removes devices that own apertures within @base and @size.
 282  *
 283  * Returns:
 284  * 0 on success, or a negative errno code otherwise
 285  */
 286 int aperture_remove_conflicting_devices(resource_size_t base, resource_size_t size,
 287                                         bool primary, const char *name)
 288 {
 289 #if IS_REACHABLE(CONFIG_FB)
 290         struct apertures_struct *a;
 291         int ret;
 292 #endif
 293
 294         /*
 295          * If a driver asked to unregister a platform device registered by
 296          * sysfb, then can be assumed that this is a driver for a display
 297          * that is set up by the system firmware and has a generic driver.
 298          *
 299          * Drivers for devices that don't have a generic driver will never
 300          * ask for this, so let's assume that a real driver for the display
 301          * was already probed and prevent sysfb to register devices later.
 302          */
 303         sysfb_disable();
 304
 305         aperture_detach_devices(base, size);
 306
 307         /*
 308          * If this is the primary adapter, there could be a VGA device
 309          * that consumes the VGA framebuffer I/O range. Remove this device
 310          * as well.
 311          */
 312         if (primary)
 313                 aperture_detach_devices(VGA_FB_PHYS_BASE, VGA_FB_PHYS_SIZE);
 314
 315 #if IS_REACHABLE(CONFIG_FB)
 316         a = alloc_apertures(1);
 317         if (!a)
 318                 return -ENOMEM;
 319
 320         a->ranges[0].base = base;
 321         a->ranges[0].size = size;
 322
 323         ret = remove_conflicting_framebuffers(a, name, primary);
 324         kfree(a);
 325
 326         if (ret)
 327                 return ret;
 328 #endif
 329
 330         return 0;
 331 }
 332 EXPORT_SYMBOL(aperture_remove_conflicting_devices);
 333
 334 /**
 335  * aperture_remove_conflicting_pci_devices - remove existing framebuffers for PCI devices
 336  * @pdev: PCI device
 337  * @name: a descriptive name of the requesting driver
 338  *
 339  * This function removes devices that own apertures within any of @pdev's
 340  * memory bars. The function assumes that PCI device with shadowed ROM
 341  * drives a primary display and therefore kicks out vga16fb as well.
 342  *
 343  * Returns:
 344  * 0 on success, or a negative errno code otherwise
 345  */
 346 int aperture_remove_conflicting_pci_devices(struct pci_dev *pdev, const char *name)
 347 {
 348         bool primary = false;
 349         resource_size_t base, size;
 350         int bar, ret;
 351
 352 #ifdef CONFIG_X86
 353         primary = pdev->resource[PCI_ROM_RESOURCE].flags & IORESOURCE_ROM_SHADOW;
 354 #endif
 355
 356         for (bar = 0; bar < PCI_STD_NUM_BARS; ++bar) {
 357                 if (!(pci_resource_flags(pdev, bar) & IORESOURCE_MEM))
 358                         continue;
 359
 360                 base = pci_resource_start(pdev, bar);
 361                 size = pci_resource_len(pdev, bar);
 362                 ret = aperture_remove_conflicting_devices(base, size, primary, name);
 363                 if (ret)
 364                         break;
 365         }
 366
 367         if (ret)
 368                 return ret;
 369
 370         /*
 371          * WARNING: Apparently we must kick fbdev drivers before vgacon,
 372          * otherwise the vga fbdev driver falls over.
 373          */
 374         ret = vga_remove_vgacon(pdev);
 375         if (ret)
 376                 return ret;
 377
 378         return 0;
 379
 380 }
 381 EXPORT_SYMBOL(aperture_remove_conflicting_pci_devices);