drivers/staging/gasket/gasket_core.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * Gasket generic driver. Defines the set of data types and functions necessary
   4  * to define a driver using the Gasket generic driver framework.
   5  *
   6  * Copyright (C) 2018 Google, Inc.
   7  */
   8 #ifndef __GASKET_CORE_H__
   9 #define __GASKET_CORE_H__
  10
  11 #include <linux/cdev.h>
  12 #include <linux/compiler.h>
  13 #include <linux/device.h>
  14 #include <linux/init.h>
  15 #include <linux/module.h>
  16 #include <linux/pci.h>
  17 #include <linux/sched.h>
  18 #include <linux/slab.h>
  19
  20 #include "gasket_constants.h"
  21
  22 /**
  23  * struct gasket_num_name - Map numbers to names.
  24  * @ein_num: Number.
  25  * @ein_name: Name associated with the number, a char pointer.
  26  *
  27  * This structure maps numbers to names. It is used to provide printable enum
  28  * names, e.g {0, "DEAD"} or {1, "ALIVE"}.
  29  */
  30 struct gasket_num_name {
  31         uint snn_num;
  32         const char *snn_name;
  33 };
  34
  35 /*
  36  * Register location for packed interrupts.
  37  * Each value indicates the location of an interrupt field (in units of
  38  * gasket_driver_desc->interrupt_pack_width) within the containing register.
  39  * In other words, this indicates the shift to use when creating a mask to
  40  * extract/set bits within a register for a given interrupt.
  41  */
  42 enum gasket_interrupt_packing {
  43         PACK_0 = 0,
  44         PACK_1 = 1,
  45         PACK_2 = 2,
  46         PACK_3 = 3,
  47         UNPACKED = 4,
  48 };
  49
  50 /* Type of the interrupt supported by the device. */
  51 enum gasket_interrupt_type {
  52         PCI_MSIX = 0,
  53         PCI_MSI = 1,
  54         PLATFORM_WIRE = 2,
  55 };
  56
  57 /*
  58  * Used to describe a Gasket interrupt. Contains an interrupt index, a register,
  59  * and packing data for that interrupt. The register and packing data
  60  * fields are relevant only for PCI_MSIX interrupt type and can be
  61  * set to 0 for everything else.
  62  */
  63 struct gasket_interrupt_desc {
  64         /* Device-wide interrupt index/number. */
  65         int index;
  66         /* The register offset controlling this interrupt. */
  67         u64 reg;
  68         /* The location of this interrupt inside register reg, if packed. */
  69         int packing;
  70 };
  71
  72 /* Offsets to the wire interrupt handling registers */
  73 struct gasket_wire_interrupt_offsets {
  74         u64 pending_bit_array;
  75         u64 mask_array;
  76 };
  77
  78 /*
  79  * This enum is used to identify memory regions being part of the physical
  80  * memory that belongs to a device.
  81  */
  82 enum mappable_area_type {
  83         PCI_BAR = 0, /* Default */
  84         BUS_REGION,  /* For SYSBUS devices, i.e. AXI etc... */
  85         COHERENT_MEMORY
  86 };
  87
  88 /*
  89  * Metadata for each BAR mapping.
  90  * This struct is used so as to track PCI memory, I/O space, AXI and coherent
  91  * memory area... i.e. memory objects which can be referenced in the device's
  92  * mmap function.
  93  */
  94 struct gasket_bar_data {
  95         /* Virtual base address. */
  96         u8 __iomem *virt_base;
  97
  98         /* Physical base address. */
  99         ulong phys_base;
 100
 101         /* Length of the mapping. */
 102         ulong length_bytes;
 103
 104         /* Type of mappable area */
 105         enum mappable_area_type type;
 106 };
 107
 108 /* Maintains device open ownership data. */
 109 struct gasket_ownership {
 110         /* 1 if the device is owned, 0 otherwise. */
 111         int is_owned;
 112
 113         /* TGID of the owner. */
 114         pid_t owner;
 115
 116         /* Count of current device opens in write mode. */
 117         int write_open_count;
 118 };
 119
 120 /* Page table modes of operation. */
 121 enum gasket_page_table_mode {
 122         /* The page table is partitionable as normal, all simple by default. */
 123         GASKET_PAGE_TABLE_MODE_NORMAL,
 124
 125         /* All entries are always simple. */
 126         GASKET_PAGE_TABLE_MODE_SIMPLE,
 127
 128         /* All entries are always extended. No extended bit is used. */
 129         GASKET_PAGE_TABLE_MODE_EXTENDED,
 130 };
 131
 132 /* Page table configuration. One per table. */
 133 struct gasket_page_table_config {
 134         /* The identifier/index of this page table. */
 135         int id;
 136
 137         /* The operation mode of this page table. */
 138         enum gasket_page_table_mode mode;
 139
 140         /* Total (first-level) entries in this page table. */
 141         ulong total_entries;
 142
 143         /* Base register for the page table. */
 144         int base_reg;
 145
 146         /*
 147          * Register containing the extended page table. This value is unused in
 148          * GASKET_PAGE_TABLE_MODE_SIMPLE and GASKET_PAGE_TABLE_MODE_EXTENDED
 149          * modes.
 150          */
 151         int extended_reg;
 152
 153         /* The bit index indicating whether a PT entry is extended. */
 154         int extended_bit;
 155 };
 156
 157 /* Maintains information about a device node. */
 158 struct gasket_cdev_info {
 159         /* The internal name of this device. */
 160         char name[GASKET_NAME_MAX];
 161
 162         /* Device number. */
 163         dev_t devt;
 164
 165         /* Kernel-internal device structure. */
 166         struct device *device;
 167
 168         /* Character device for real. */
 169         struct cdev cdev;
 170
 171         /* Flag indicating if cdev_add has been called for the devices. */
 172         int cdev_added;
 173
 174         /* Pointer to the overall gasket_dev struct for this device. */
 175         struct gasket_dev *gasket_dev_ptr;
 176
 177         /* Ownership data for the device in question. */
 178         struct gasket_ownership ownership;
 179 };
 180
 181 /* Describes the offset and length of mmapable device BAR regions. */
 182 struct gasket_mappable_region {
 183         u64 start;
 184         u64 length_bytes;
 185 };
 186
 187 /* Describe the offset, size, and permissions for a device bar. */
 188 struct gasket_bar_desc {
 189         /*
 190          * The size of each PCI BAR range, in bytes. If a value is 0, that BAR
 191          * will not be mapped into kernel space at all.
 192          * For devices with 64 bit BARs, only elements 0, 2, and 4 should be
 193          * populated, and 1, 3, and 5 should be set to 0.
 194          * For example, for a device mapping 1M in each of the first two 64-bit
 195          * BARs, this field would be set as { 0x100000, 0, 0x100000, 0, 0, 0 }
 196          * (one number per bar_desc struct.)
 197          */
 198         u64 size;
 199         /* The permissions for this bar. (Should be VM_WRITE/VM_READ/VM_EXEC,
 200          * and can be or'd.) If set to GASKET_NOMAP, the bar will
 201          * not be used for mmapping.
 202          */
 203         ulong permissions;
 204         /* The memory address corresponding to the base of this bar, if used. */
 205         u64 base;
 206         /* The number of mappable regions in this bar. */
 207         int num_mappable_regions;
 208
 209         /* The mappable subregions of this bar. */
 210         const struct gasket_mappable_region *mappable_regions;
 211
 212         /* Type of mappable area */
 213         enum mappable_area_type type;
 214 };
 215
 216 /* Describes the offset, size, and permissions for a coherent buffer. */
 217 struct gasket_coherent_buffer_desc {
 218         /* The size of the coherent buffer. */
 219         u64 size;
 220
 221         /* The permissions for this bar. (Should be VM_WRITE/VM_READ/VM_EXEC,
 222          * and can be or'd.) If set to GASKET_NOMAP, the bar will
 223          * not be used for mmaping.
 224          */
 225         ulong permissions;
 226
 227         /* device side address. */
 228         u64 base;
 229 };
 230
 231 /* Coherent buffer structure. */
 232 struct gasket_coherent_buffer {
 233         /* Virtual base address. */
 234         u8 __iomem *virt_base;
 235
 236         /* Physical base address. */
 237         ulong phys_base;
 238
 239         /* Length of the mapping. */
 240         ulong length_bytes;
 241 };
 242
 243 /* Description of Gasket-specific permissions in the mmap field. */
 244 enum gasket_mapping_options { GASKET_NOMAP = 0 };
 245
 246 /* This struct represents an undefined bar that should never be mapped. */
 247 #define GASKET_UNUSED_BAR                                                      \
 248         {                                                                      \
 249                 0, GASKET_NOMAP, 0, 0, NULL, 0                                 \
 250         }
 251
 252 /* Internal data for a Gasket device. See gasket_core.c for more information. */
 253 struct gasket_internal_desc;
 254
 255 #define MAX_NUM_COHERENT_PAGES 16
 256
 257 /*
 258  * Device data for Gasket device instances.
 259  *
 260  * This structure contains the data required to manage a Gasket device.
 261  */
 262 struct gasket_dev {
 263         /* Pointer to the internal driver description for this device. */
 264         struct gasket_internal_desc *internal_desc;
 265
 266         /* Device info */
 267         struct device *dev;
 268
 269         /* PCI subsystem metadata. */
 270         struct pci_dev *pci_dev;
 271
 272         /* This device's index into internal_desc->devs. */
 273         int dev_idx;
 274
 275         /* The name of this device, as reported by the kernel. */
 276         char kobj_name[GASKET_NAME_MAX];
 277
 278         /* Virtual address of mapped BAR memory range. */
 279         struct gasket_bar_data bar_data[GASKET_NUM_BARS];
 280
 281         /* Coherent buffer. */
 282         struct gasket_coherent_buffer coherent_buffer;
 283
 284         /* Number of page tables for this device. */
 285         int num_page_tables;
 286
 287         /* Address translations. Page tables have a private implementation. */
 288         struct gasket_page_table *page_table[GASKET_MAX_NUM_PAGE_TABLES];
 289
 290         /* Interrupt data for this device. */
 291         struct gasket_interrupt_data *interrupt_data;
 292
 293         /* Status for this device - GASKET_STATUS_ALIVE or _DEAD. */
 294         uint status;
 295
 296         /* Number of times this device has been reset. */
 297         uint reset_count;
 298
 299         /* Dev information for the cdev node. */
 300         struct gasket_cdev_info dev_info;
 301
 302         /* Hardware revision value for this device. */
 303         int hardware_revision;
 304
 305         /* Protects access to per-device data (i.e. this structure). */
 306         struct mutex mutex;
 307
 308         /* cdev hash tracking/membership structure, Accel and legacy. */
 309         /* Unused until Accel is upstreamed. */
 310         struct hlist_node hlist_node;
 311         struct hlist_node legacy_hlist_node;
 312 };
 313
 314 /* Type of the ioctl handler callback. */
 315 typedef long (*gasket_ioctl_handler_cb_t)(struct file *file, uint cmd,
 316                                           void __user *argp);
 317 /* Type of the ioctl permissions check callback. See below. */
 318 typedef int (*gasket_ioctl_permissions_cb_t)(struct file *filp, uint cmd,
 319                                              void __user *argp);
 320
 321 /*
 322  * Device type descriptor.
 323  *
 324  * This structure contains device-specific data needed to identify and address a
 325  * type of device to be administered via the Gasket generic driver.
 326  *
 327  * Device IDs are per-driver. In other words, two drivers using the Gasket
 328  * framework will each have a distinct device 0 (for example).
 329  */
 330 struct gasket_driver_desc {
 331         /* The name of this device type. */
 332         const char *name;
 333
 334         /* The name of this specific device model. */
 335         const char *chip_model;
 336
 337         /* The version of the chip specified in chip_model. */
 338         const char *chip_version;
 339
 340         /* The version of this driver: "1.0.0", "2.1.3", etc. */
 341         const char *driver_version;
 342
 343         /*
 344          * Non-zero if we should create "legacy" (device and device-class-
 345          * specific) character devices and sysfs nodes.
 346          */
 347         /* Unused until Accel is upstreamed. */
 348         int legacy_support;
 349
 350         /* Major and minor numbers identifying the device. */
 351         int major, minor;
 352
 353         /* Module structure for this driver. */
 354         struct module *module;
 355
 356         /* PCI ID table. */
 357         const struct pci_device_id *pci_id_table;
 358
 359         /* The number of page tables handled by this driver. */
 360         int num_page_tables;
 361
 362         /* The index of the bar containing the page tables. */
 363         int page_table_bar_index;
 364
 365         /* Registers used to control each page table. */
 366         const struct gasket_page_table_config *page_table_configs;
 367
 368         /* The bit index indicating whether a PT entry is extended. */
 369         int page_table_extended_bit;
 370
 371         /*
 372          * Legacy mmap address adjusment for legacy devices only. Should be 0
 373          * for any new device.
 374          */
 375         ulong legacy_mmap_address_offset;
 376
 377         /* Set of 6 bar descriptions that describe all PCIe bars.
 378          * Note that BUS/AXI devices (i.e. non PCI devices) use those.
 379          */
 380         struct gasket_bar_desc bar_descriptions[GASKET_NUM_BARS];
 381
 382         /*
 383          * Coherent buffer description.
 384          */
 385         struct gasket_coherent_buffer_desc coherent_buffer_description;
 386
 387         /* Offset of wire interrupt registers. */
 388         const struct gasket_wire_interrupt_offsets *wire_interrupt_offsets;
 389
 390         /* Interrupt type. (One of gasket_interrupt_type). */
 391         int interrupt_type;
 392
 393         /* Index of the bar containing the interrupt registers to program. */
 394         int interrupt_bar_index;
 395
 396         /* Number of interrupts in the gasket_interrupt_desc array */
 397         int num_interrupts;
 398
 399         /* Description of the interrupts for this device. */
 400         const struct gasket_interrupt_desc *interrupts;
 401
 402         /*
 403          * If this device packs multiple interrupt->MSI-X mappings into a
 404          * single register (i.e., "uses packed interrupts"), only a single bit
 405          * width is supported for each interrupt mapping (unpacked/"full-width"
 406          * interrupts are always supported). This value specifies that width. If
 407          * packed interrupts are not used, this value is ignored.
 408          */
 409         int interrupt_pack_width;
 410
 411         /* Driver callback functions - all may be NULL */
 412         /*
 413          * device_open_cb: Callback for when a device node is opened in write
 414          * mode.
 415          * @dev: The gasket_dev struct for this driver instance.
 416          *
 417          * This callback should perform device-specific setup that needs to
 418          * occur only once when a device is first opened.
 419          */
 420         int (*device_open_cb)(struct gasket_dev *dev);
 421
 422         /*
 423          * device_release_cb: Callback when a device is closed.
 424          * @gasket_dev: The gasket_dev struct for this driver instance.
 425          *
 426          * This callback is called whenever a device node fd is closed, as
 427          * opposed to device_close_cb, which is called when the _last_
 428          * descriptor for an open file is closed. This call is intended to
 429          * handle any per-user or per-fd cleanup.
 430          */
 431         int (*device_release_cb)(struct gasket_dev *gasket_dev,
 432                                  struct file *file);
 433
 434         /*
 435          * device_close_cb: Callback for when a device node is closed for the
 436          * last time.
 437          * @dev: The gasket_dev struct for this driver instance.
 438          *
 439          * This callback should perform device-specific cleanup that only
 440          * needs to occur when the last reference to a device node is closed.
 441          *
 442          * This call is intended to handle and device-wide cleanup, as opposed
 443          * to per-fd cleanup (which should be handled by device_release_cb).
 444          */
 445         int (*device_close_cb)(struct gasket_dev *dev);
 446
 447         /*
 448          * get_mappable_regions_cb: Get descriptors of mappable device memory.
 449          * @gasket_dev: Pointer to the struct gasket_dev for this device.
 450          * @bar_index: BAR for which to retrieve memory ranges.
 451          * @mappable_regions: Out-pointer to the list of mappable regions on the
 452          * device/BAR for this process.
 453          * @num_mappable_regions: Out-pointer for the size of mappable_regions.
 454          *
 455          * Called when handling mmap(), this callback is used to determine which
 456          * regions of device memory may be mapped by the current process. This
 457          * information is then compared to mmap request to determine which
 458          * regions to actually map.
 459          */
 460         int (*get_mappable_regions_cb)(struct gasket_dev *gasket_dev,
 461                                        int bar_index,
 462                                        struct gasket_mappable_region **mappable_regions,
 463                                        int *num_mappable_regions);
 464
 465         /*
 466          * ioctl_permissions_cb: Check permissions for generic ioctls.
 467          * @filp: File structure pointer describing this node usage session.
 468          * @cmd: ioctl number to handle.
 469          * @arg: ioctl-specific data pointer.
 470          *
 471          * Returns 1 if the ioctl may be executed, 0 otherwise. If this callback
 472          * isn't specified a default routine will be used, that only allows the
 473          * original device opener (i.e, the "owner") to execute state-affecting
 474          * ioctls.
 475          */
 476         gasket_ioctl_permissions_cb_t ioctl_permissions_cb;
 477
 478         /*
 479          * ioctl_handler_cb: Callback to handle device-specific ioctls.
 480          * @filp: File structure pointer describing this node usage session.
 481          * @cmd: ioctl number to handle.
 482          * @arg: ioctl-specific data pointer.
 483          *
 484          * Invoked whenever an ioctl is called that the generic Gasket
 485          * framework doesn't support. If no cb is registered, unknown ioctls
 486          * return -EINVAL. Should return an error status (either -EINVAL or
 487          * the error result of the ioctl being handled).
 488          */
 489         gasket_ioctl_handler_cb_t ioctl_handler_cb;
 490
 491         /*
 492          * device_status_cb: Callback to determine device health.
 493          * @dev: Pointer to the gasket_dev struct for this device.
 494          *
 495          * Called to determine if the device is healthy or not. Should return
 496          * a member of the gasket_status_type enum.
 497          *
 498          */
 499         int (*device_status_cb)(struct gasket_dev *dev);
 500
 501         /*
 502          * hardware_revision_cb: Get the device's hardware revision.
 503          * @dev: Pointer to the gasket_dev struct for this device.
 504          *
 505          * Called to determine the reported rev of the physical hardware.
 506          * Revision should be >0. A negative return value is an error.
 507          */
 508         int (*hardware_revision_cb)(struct gasket_dev *dev);
 509
 510         /*
 511          * device_reset_cb: Reset the hardware in question.
 512          * @dev: Pointer to the gasket_dev structure for this device.
 513          *
 514          * Called by reset ioctls. This function should not
 515          * lock the gasket_dev mutex. It should return 0 on success
 516          * and an error on failure.
 517          */
 518         int (*device_reset_cb)(struct gasket_dev *dev);
 519 };
 520
 521 /*
 522  * Register the specified device type with the framework.
 523  * @desc: Populated/initialized device type descriptor.
 524  *
 525  * This function does _not_ take ownership of desc; the underlying struct must
 526  * exist until the matching call to gasket_unregister_device.
 527  * This function should be called from your driver's module_init function.
 528  */
 529 int gasket_register_device(const struct gasket_driver_desc *desc);
 530
 531 /*
 532  * Remove the specified device type from the framework.
 533  * @desc: Descriptor for the device type to unregister; it should have been
 534  *        passed to gasket_register_device in a previous call.
 535  *
 536  * This function should be called from your driver's module_exit function.
 537  */
 538 void gasket_unregister_device(const struct gasket_driver_desc *desc);
 539
 540 /* Add a PCI gasket device. */
 541 int gasket_pci_add_device(struct pci_dev *pci_dev,
 542                           struct gasket_dev **gasket_devp);
 543 /* Remove a PCI gasket device. */
 544 void gasket_pci_remove_device(struct pci_dev *pci_dev);
 545
 546 /* Enable a Gasket device. */
 547 int gasket_enable_device(struct gasket_dev *gasket_dev);
 548
 549 /* Disable a Gasket device. */
 550 void gasket_disable_device(struct gasket_dev *gasket_dev);
 551
 552 /*
 553  * Reset the Gasket device.
 554  * @gasket_dev: Gasket device struct.
 555  *
 556  * Calls device_reset_cb. Returns 0 on success and an error code othewrise.
 557  * gasket_reset_nolock will not lock the mutex, gasket_reset will.
 558  *
 559  */
 560 int gasket_reset(struct gasket_dev *gasket_dev);
 561 int gasket_reset_nolock(struct gasket_dev *gasket_dev);
 562
 563 /*
 564  * Memory management functions. These will likely be spun off into their own
 565  * file in the future.
 566  */
 567
 568 /* Unmaps the specified mappable region from a VMA. */
 569 int gasket_mm_unmap_region(const struct gasket_dev *gasket_dev,
 570                            struct vm_area_struct *vma,
 571                            const struct gasket_mappable_region *map_region);
 572
 573 /*
 574  * Get the ioctl permissions callback.
 575  * @gasket_dev: Gasket device structure.
 576  */
 577 gasket_ioctl_permissions_cb_t
 578 gasket_get_ioctl_permissions_cb(struct gasket_dev *gasket_dev);
 579
 580 /**
 581  * Lookup a name by number in a num_name table.
 582  * @num: Number to lookup.
 583  * @table: Array of num_name structures, the table for the lookup.
 584  *
 585  */
 586 const char *gasket_num_name_lookup(uint num,
 587                                    const struct gasket_num_name *table);
 588
 589 /* Handy inlines */
 590 static inline ulong gasket_dev_read_64(struct gasket_dev *gasket_dev, int bar,
 591                                        ulong location)
 592 {
 593         return readq(&gasket_dev->bar_data[bar].virt_base[location]);
 594 }
 595
 596 static inline void gasket_dev_write_64(struct gasket_dev *dev, u64 value,
 597                                        int bar, ulong location)
 598 {
 599         writeq(value, &dev->bar_data[bar].virt_base[location]);
 600 }
 601
 602 static inline void gasket_dev_write_32(struct gasket_dev *dev, u32 value,
 603                                        int bar, ulong location)
 604 {
 605         writel(value, &dev->bar_data[bar].virt_base[location]);
 606 }
 607
 608 static inline u32 gasket_dev_read_32(struct gasket_dev *dev, int bar,
 609                                      ulong location)
 610 {
 611         return readl(&dev->bar_data[bar].virt_base[location]);
 612 }
 613
 614 static inline void gasket_read_modify_write_64(struct gasket_dev *dev, int bar,
 615                                                ulong location, u64 value,
 616                                                u64 mask_width, u64 mask_shift)
 617 {
 618         u64 mask, tmp;
 619
 620         tmp = gasket_dev_read_64(dev, bar, location);
 621         mask = ((1ULL << mask_width) - 1) << mask_shift;
 622         tmp = (tmp & ~mask) | (value << mask_shift);
 623         gasket_dev_write_64(dev, tmp, bar, location);
 624 }
 625
 626 static inline void gasket_read_modify_write_32(struct gasket_dev *dev, int bar,
 627                                                ulong location, u32 value,
 628                                                u32 mask_width, u32 mask_shift)
 629 {
 630         u32 mask, tmp;
 631
 632         tmp = gasket_dev_read_32(dev, bar, location);
 633         mask = ((1 << mask_width) - 1) << mask_shift;
 634         tmp = (tmp & ~mask) | (value << mask_shift);
 635         gasket_dev_write_32(dev, tmp, bar, location);
 636 }
 637
 638 /* Get the Gasket driver structure for a given device. */
 639 const struct gasket_driver_desc *gasket_get_driver_desc(struct gasket_dev *dev);
 640
 641 /* Get the device structure for a given device. */
 642 struct device *gasket_get_device(struct gasket_dev *dev);
 643
 644 /* Helper function, Asynchronous waits on a given set of bits. */
 645 int gasket_wait_with_reschedule(struct gasket_dev *gasket_dev, int bar,
 646                                 u64 offset, u64 mask, u64 val,
 647                                 uint max_retries, u64 delay_ms);
 648
 649 #endif /* __GASKET_CORE_H__ */