include/pciaccess.h

   1 /*
   2  * (C) Copyright IBM Corporation 2006
   3  * All Rights Reserved.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a
   6  * copy of this software and associated documentation files (the "Software"),
   7  * to deal in the Software without restriction, including without limitation
   8  * on the rights to use, copy, modify, merge, publish, distribute, sub
   9  * license, and/or sell copies of the Software, and to permit persons to whom
  10  * the Software is furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice (including the next
  13  * paragraph) shall be included in all copies or substantial portions of the
  14  * Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL
  19  * IBM AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  22  * DEALINGS IN THE SOFTWARE.
  23  */
  24 /*
  25  * Copyright (c) 2007 Paulo R. Zanoni, Tiago Vignatti
  26  *
  27  * Permission is hereby granted, free of charge, to any person
  28  * obtaining a copy of this software and associated documentation
  29  * files (the "Software"), to deal in the Software without
  30  * restriction, including without limitation the rights to use,
  31  * copy, modify, merge, publish, distribute, sublicense, and/or sell
  32  * copies of the Software, and to permit persons to whom the
  33  * Software is furnished to do so, subject to the following
  34  * conditions:
  35  *
  36  * The above copyright notice and this permission notice shall be
  37  * included in all copies or substantial portions of the Software.
  38  *
  39  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  40  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  41  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  42  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  43  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  44  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  45  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  46  * OTHER DEALINGS IN THE SOFTWARE.
  47  *
  48  */
  49
  50 /**
  51  * \file pciaccess.h
  52  *
  53  * \author Ian Romanick <idr@us.ibm.com>
  54  */
  55
  56 #ifndef PCIACCESS_H
  57 #define PCIACCESS_H
  58
  59 #include <inttypes.h>
  60
  61 #if __GNUC__ >= 3
  62 #define __deprecated __attribute__((deprecated))
  63 #else
  64 #define __deprecated
  65 #endif
  66
  67 typedef uint64_t pciaddr_t;
  68
  69 struct pci_device;
  70 struct pci_device_iterator;
  71 struct pci_id_match;
  72 struct pci_slot_match;
  73
  74 #ifdef __cplusplus
  75 extern "C" {
  76 #endif
  77
  78 int pci_device_is_boot_vga(struct pci_device *dev);
  79
  80 int pci_device_read_rom(struct pci_device *dev, void *buffer);
  81
  82 int  __deprecated pci_device_map_region(struct pci_device *dev,
  83     unsigned region, int write_enable);
  84
  85 int __deprecated pci_device_unmap_region(struct pci_device *dev,
  86     unsigned region);
  87
  88 int pci_device_map_range(struct pci_device *dev, pciaddr_t base,
  89     pciaddr_t size, unsigned map_flags, void **addr);
  90
  91 int pci_device_unmap_range(struct pci_device *dev, void *memory,
  92     pciaddr_t size);
  93
  94 int __deprecated pci_device_map_memory_range(struct pci_device *dev,
  95     pciaddr_t base, pciaddr_t size, int write_enable, void **addr);
  96
  97 int __deprecated pci_device_unmap_memory_range(struct pci_device *dev,
  98     void *memory, pciaddr_t size);
  99
 100 int pci_device_probe(struct pci_device *dev);
 101
 102 const struct pci_agp_info *pci_device_get_agp_info(struct pci_device *dev);
 103
 104 const struct pci_bridge_info *pci_device_get_bridge_info(
 105     struct pci_device *dev);
 106
 107 const struct pci_pcmcia_bridge_info *pci_device_get_pcmcia_bridge_info(
 108     struct pci_device *dev);
 109
 110 int pci_device_get_bridge_buses(struct pci_device *dev, int *primary_bus,
 111     int *secondary_bus, int *subordinate_bus);
 112
 113 int pci_system_init(void);
 114
 115 void pci_system_init_dev_mem(int fd);
 116
 117 void pci_system_cleanup(void);
 118
 119 struct pci_device_iterator *pci_slot_match_iterator_create(
 120     const struct pci_slot_match *match);
 121
 122 struct pci_device_iterator *pci_id_match_iterator_create(
 123     const struct pci_id_match *match);
 124
 125 void pci_iterator_destroy(struct pci_device_iterator *iter);
 126
 127 struct pci_device *pci_device_next(struct pci_device_iterator *iter);
 128
 129 struct pci_device *pci_device_find_by_slot(uint32_t domain, uint32_t bus,
 130     uint32_t dev, uint32_t func);
 131
 132 void pci_get_strings(const struct pci_id_match *m,
 133     const char **device_name, const char **vendor_name,
 134     const char **subdevice_name, const char **subvendor_name);
 135 const char *pci_device_get_device_name(const struct pci_device *dev);
 136 const char *pci_device_get_subdevice_name(const struct pci_device *dev);
 137 const char *pci_device_get_vendor_name(const struct pci_device *dev);
 138 const char *pci_device_get_subvendor_name(const struct pci_device *dev);
 139
 140 void pci_device_enable(struct pci_device *dev);
 141
 142 int pci_device_cfg_read    (struct pci_device *dev, void *data,
 143     pciaddr_t offset, pciaddr_t size, pciaddr_t *bytes_read);
 144 int pci_device_cfg_read_u8 (struct pci_device *dev, uint8_t  *data,
 145     pciaddr_t offset);
 146 int pci_device_cfg_read_u16(struct pci_device *dev, uint16_t *data,
 147     pciaddr_t offset);
 148 int pci_device_cfg_read_u32(struct pci_device *dev, uint32_t *data,
 149     pciaddr_t offset);
 150
 151 int pci_device_cfg_write    (struct pci_device *dev, const void *data,
 152     pciaddr_t offset, pciaddr_t size, pciaddr_t *bytes_written);
 153 int pci_device_cfg_write_u8 (struct pci_device *dev, uint8_t  data,
 154     pciaddr_t offset);
 155 int pci_device_cfg_write_u16(struct pci_device *dev, uint16_t data,
 156     pciaddr_t offset);
 157 int pci_device_cfg_write_u32(struct pci_device *dev, uint32_t data,
 158     pciaddr_t offset);
 159 int pci_device_cfg_write_bits(struct pci_device *dev, uint32_t mask,
 160     uint32_t data, pciaddr_t offset);
 161
 162 #ifdef __cplusplus
 163 }
 164 #endif
 165
 166 /**
 167  * \name Mapping flags passed to \c pci_device_map_range
 168  */
 169 /*@{*/
 170 #define PCI_DEV_MAP_FLAG_WRITABLE       (1U<<0)
 171 #define PCI_DEV_MAP_FLAG_WRITE_COMBINE  (1U<<1)
 172 #define PCI_DEV_MAP_FLAG_CACHABLE       (1U<<2)
 173 /*@}*/
 174
 175
 176 #define PCI_MATCH_ANY  (~0)
 177
 178 /**
 179  * Compare two PCI ID values (either vendor or device).  This is used
 180  * internally to compare the fields of \c pci_id_match to the fields of
 181  * \c pci_device.
 182  */
 183 #define PCI_ID_COMPARE(a, b) \
 184     (((a) == PCI_MATCH_ANY) || ((a) == (b)))
 185
 186 /**
 187  */
 188 struct pci_id_match {
 189     /**
 190      * \name Device / vendor matching controls
 191      *
 192      * Control the search based on the device, vendor, subdevice, or subvendor
 193      * IDs.  Setting any of these fields to \c PCI_MATCH_ANY will cause the
 194      * field to not be used in the comparison.
 195      */
 196     /*@{*/
 197     uint32_t    vendor_id;
 198     uint32_t    device_id;
 199     uint32_t    subvendor_id;
 200     uint32_t    subdevice_id;
 201     /*@}*/
 202
 203
 204     /**
 205      * \name Device class matching controls
 206      *
 207      */
 208     /*@{*/
 209     uint32_t    device_class;
 210     uint32_t    device_class_mask;
 211     /*@}*/
 212
 213     intptr_t    match_data;
 214 };
 215
 216
 217 /**
 218  */
 219 struct pci_slot_match {
 220     /**
 221      * \name Device slot matching controls
 222      *
 223      * Control the search based on the domain, bus, slot, and function of
 224      * the device.  Setting any of these fields to \c PCI_MATCH_ANY will cause
 225      * the field to not be used in the comparison.
 226      */
 227     /*@{*/
 228     uint32_t    domain;
 229     uint32_t    bus;
 230     uint32_t    dev;
 231     uint32_t    func;
 232     /*@}*/
 233
 234     intptr_t    match_data;
 235 };
 236
 237 /**
 238  * BAR descriptor for a PCI device.
 239  */
 240 struct pci_mem_region {
 241     /**
 242      * When the region is mapped, this is the pointer to the memory.
 243      *
 244      * This field is \b only set when the deprecated \c pci_device_map_region
 245      * interface is used.  Use \c pci_device_map_range instead.
 246      *
 247      * \deprecated
 248      */
 249     void *memory;
 250
 251
 252     /**
 253      * Base physical address of the region within its bus / domain.
 254      *
 255      * \warning
 256      * This address is really only useful to other devices in the same
 257      * domain.  It's probably \b not the address applications will ever
 258      * use.
 259      *
 260      * \warning
 261      * Most (all?) platform back-ends leave this field unset.
 262      */
 263     pciaddr_t bus_addr;
 264
 265
 266     /**
 267      * Base physical address of the region from the CPU's point of view.
 268      *
 269      * This address is typically passed to \c pci_device_map_range to create
 270      * a mapping of the region to the CPU's virtual address space.
 271      */
 272     pciaddr_t base_addr;
 273
 274
 275     /**
 276      * Size, in bytes, of the region.
 277      */
 278     pciaddr_t size;
 279
 280
 281     /**
 282      * Is the region I/O ports or memory?
 283      */
 284     unsigned is_IO:1;
 285
 286     /**
 287      * Is the memory region prefetchable?
 288      *
 289      * \note
 290      * This can only be set if \c is_IO is not set.
 291      */
 292     unsigned is_prefetchable:1;
 293
 294
 295     /**
 296      * Is the memory at a 64-bit address?
 297      *
 298      * \note
 299      * This can only be set if \c is_IO is not set.
 300      */
 301     unsigned is_64:1;
 302 };
 303
 304
 305 /**
 306  * PCI device.
 307  *
 308  * Contains all of the information about a particular PCI device.
 309  */
 310 struct pci_device {
 311     /**
 312      * \name Device bus identification.
 313      *
 314      * Complete bus identification, including domain, of the device.  On
 315      * platforms that do not support PCI domains (e.g., 32-bit x86 hardware),
 316      * the domain will always be zero.
 317      */
 318     /*@{*/
 319     uint16_t    domain;
 320     uint8_t     bus;
 321     uint8_t     dev;
 322     uint8_t     func;
 323     /*@}*/
 324
 325
 326     /**
 327      * \name Vendor / device ID
 328      *
 329      * The vendor ID, device ID, and sub-IDs for the device.
 330      */
 331     /*@{*/
 332     uint16_t    vendor_id;
 333     uint16_t    device_id;
 334     uint16_t    subvendor_id;
 335     uint16_t    subdevice_id;
 336     /*@}*/
 337
 338     /**
 339      * Device's class, subclass, and programming interface packed into a
 340      * single 32-bit value.  The class is at bits [23:16], subclass is at
 341      * bits [15:8], and programming interface is at [7:0].
 342      */
 343     uint32_t    device_class;
 344
 345
 346     /**
 347      * Device revision number, as read from the configuration header.
 348      */
 349     uint8_t     revision;
 350
 351
 352     /**
 353      * BAR descriptors for the device.
 354      */
 355     struct pci_mem_region regions[6];
 356
 357
 358     /**
 359      * Size, in bytes, of the device's expansion ROM.
 360      */
 361     pciaddr_t   rom_size;
 362
 363
 364     /**
 365      * IRQ associated with the device.  If there is no IRQ, this value will
 366      * be -1.
 367      */
 368     int irq;
 369
 370
 371     /**
 372      * Storage for user data.  Users of the library can store arbitrary
 373      * data in this pointer.  The library will not use it for any purpose.
 374      * It is the user's responsability to free this memory before destroying
 375      * the \c pci_device structure.
 376      */
 377     intptr_t user_data;
 378
 379     /**
 380       * Used by the VGA arbiter. Type of resource decoded by the device and
 381       * the file descriptor (/dev/vga_arbiter). */
 382     int vgaarb_rsrc;
 383     int vgaarb_fd;
 384 };
 385
 386
 387 /**
 388  * Description of the AGP capability of the device.
 389  *
 390  * \sa pci_device_get_agp_info
 391  */
 392 struct pci_agp_info {
 393     /**
 394      * Offset of the AGP registers in the devices configuration register
 395      * space.  This is generally used so that the offset of the AGP command
 396      * register can be determined.
 397      */
 398     unsigned    config_offset;
 399
 400
 401     /**
 402      * \name AGP major / minor version.
 403      */
 404     /*@{*/
 405     uint8_t     major_version;
 406     uint8_t     minor_version;
 407     /*@}*/
 408
 409     /**
 410      * Logical OR of the supported AGP rates.  For example, a value of 0x07
 411      * means that the device can support 1x, 2x, and 4x.  A value of 0x0c
 412      * means that the device can support 8x and 4x.
 413      */
 414     uint8_t    rates;
 415
 416     unsigned int    fast_writes:1;  /**< Are fast-writes supported? */
 417     unsigned int    addr64:1;
 418     unsigned int    htrans:1;
 419     unsigned int    gart64:1;
 420     unsigned int    coherent:1;
 421     unsigned int    sideband:1;     /**< Is side-band addressing supported? */
 422     unsigned int    isochronus:1;
 423
 424     uint8_t    async_req_size;
 425     uint8_t    calibration_cycle_timing;
 426     uint8_t    max_requests;
 427 };
 428
 429 /**
 430  * Description of a PCI-to-PCI bridge device.
 431  *
 432  * \sa pci_device_get_bridge_info
 433  */
 434 struct pci_bridge_info {
 435     uint8_t    primary_bus;
 436     uint8_t    secondary_bus;
 437     uint8_t    subordinate_bus;
 438     uint8_t    secondary_latency_timer;
 439
 440     uint8_t     io_type;
 441     uint8_t     mem_type;
 442     uint8_t     prefetch_mem_type;
 443
 444     uint16_t    secondary_status;
 445     uint16_t    bridge_control;
 446
 447     uint32_t    io_base;
 448     uint32_t    io_limit;
 449
 450     uint32_t    mem_base;
 451     uint32_t    mem_limit;
 452
 453     uint64_t    prefetch_mem_base;
 454     uint64_t    prefetch_mem_limit;
 455 };
 456
 457 /**
 458  * Description of a PCI-to-PCMCIA bridge device.
 459  *
 460  * \sa pci_device_get_pcmcia_bridge_info
 461  */
 462 struct pci_pcmcia_bridge_info {
 463     uint8_t    primary_bus;
 464     uint8_t    card_bus;
 465     uint8_t    subordinate_bus;
 466     uint8_t    cardbus_latency_timer;
 467
 468     uint16_t    secondary_status;
 469     uint16_t    bridge_control;
 470
 471     struct {
 472         uint32_t    base;
 473         uint32_t    limit;
 474     } io[2];
 475
 476     struct {
 477         uint32_t    base;
 478         uint32_t    limit;
 479     } mem[2];
 480
 481 };
 482
 483
 484 /**
 485  * VGA Arbiter definitions, functions and related.
 486  */
 487
 488 /* Legacy VGA regions */
 489 #define VGA_ARB_RSRC_NONE       0x00
 490 #define VGA_ARB_RSRC_LEGACY_IO  0x01
 491 #define VGA_ARB_RSRC_LEGACY_MEM 0x02
 492 /* Non-legacy access */
 493 #define VGA_ARB_RSRC_NORMAL_IO  0x04
 494 #define VGA_ARB_RSRC_NORMAL_MEM 0x08
 495
 496 int  pci_device_vgaarb_init         (struct pci_device *dev);
 497 void pci_device_vgaarb_fini         (struct pci_device *dev);
 498 int  pci_device_vgaarb_set_target   (struct pci_device *dev);
 499 int  pci_device_vgaarb_decodes      (struct pci_device *dev);
 500 int  pci_device_vgaarb_lock         (struct pci_device *dev);
 501 int  pci_device_vgaarb_trylock      (struct pci_device *dev);
 502 int  pci_device_vgaarb_unlock       (struct pci_device *dev);
 503
 504 #endif /* PCIACCESS_H */