source/include/pciaccess.h

0001 /*
0002  * (C) Copyright IBM Corporation 2006
0003  * Copyright 2009 Red Hat, Inc.
0004  * All Rights Reserved.
0005  *
0006  * Permission is hereby granted, free of charge, to any person obtaining a
0007  * copy of this software and associated documentation files (the "Software"),
0008  * to deal in the Software without restriction, including without limitation
0009  * on the rights to use, copy, modify, merge, publish, distribute, sub
0010  * license, and/or sell copies of the Software, and to permit persons to whom
0011  * the Software is furnished to do so, subject to the following conditions:
0012  *
0013  * The above copyright notice and this permission notice (including the next
0014  * paragraph) shall be included in all copies or substantial portions of the
0015  * Software.
0016  *
0017  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0018  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0019  * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL
0020  * IBM AND/OR THEIR SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
0021  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
0022  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
0023  * DEALINGS IN THE SOFTWARE.
0024  */
0025 /*
0026  * Copyright (c) 2007 Paulo R. Zanoni, Tiago Vignatti
0027  *
0028  * Permission is hereby granted, free of charge, to any person
0029  * obtaining a copy of this software and associated documentation
0030  * files (the "Software"), to deal in the Software without
0031  * restriction, including without limitation the rights to use,
0032  * copy, modify, merge, publish, distribute, sublicense, and/or sell
0033  * copies of the Software, and to permit persons to whom the
0034  * Software is furnished to do so, subject to the following
0035  * conditions:
0036  *
0037  * The above copyright notice and this permission notice shall be
0038  * included in all copies or substantial portions of the Software.
0039  *
0040  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
0041  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
0042  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
0043  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
0044  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
0045  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
0046  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
0047  * OTHER DEALINGS IN THE SOFTWARE.
0048  *
0049  */
0050
0051 /**
0052  * \file pciaccess.h
0053  *
0054  * \author Ian Romanick <idr@us.ibm.com>
0055  */
0056
0057 #ifndef PCIACCESS_H
0058 #define PCIACCESS_H
0059
0060 #include <inttypes.h>
0061
0062 #if (__GNUC__ >= 3) || (__SUNPRO_C >= 0x5130)
0063 #define __deprecated __attribute__((deprecated))
0064 #else
0065 #define __deprecated
0066 #endif
0067
0068 typedef uint64_t pciaddr_t;
0069
0070 struct pci_device;
0071 struct pci_device_iterator;
0072 struct pci_id_match;
0073 struct pci_slot_match;
0074
0075 #ifdef __cplusplus
0076 extern "C" {
0077 #endif
0078
0079 int pci_device_has_kernel_driver(struct pci_device *dev);
0080
0081 int pci_device_is_boot_vga(struct pci_device *dev);
0082
0083 int pci_device_read_rom(struct pci_device *dev, void *buffer);
0084
0085 int  __deprecated pci_device_map_region(struct pci_device *dev,
0086     unsigned region, int write_enable);
0087
0088 int __deprecated pci_device_unmap_region(struct pci_device *dev,
0089     unsigned region);
0090
0091 int pci_device_map_range(struct pci_device *dev, pciaddr_t base,
0092     pciaddr_t size, unsigned map_flags, void **addr);
0093
0094 int pci_device_unmap_range(struct pci_device *dev, void *memory,
0095     pciaddr_t size);
0096
0097 int __deprecated pci_device_map_memory_range(struct pci_device *dev,
0098     pciaddr_t base, pciaddr_t size, int write_enable, void **addr);
0099
0100 int __deprecated pci_device_unmap_memory_range(struct pci_device *dev,
0101     void *memory, pciaddr_t size);
0102
0103 int pci_device_probe(struct pci_device *dev);
0104
0105 const struct pci_agp_info *pci_device_get_agp_info(struct pci_device *dev);
0106
0107 const struct pci_bridge_info *pci_device_get_bridge_info(
0108     struct pci_device *dev);
0109
0110 const struct pci_pcmcia_bridge_info *pci_device_get_pcmcia_bridge_info(
0111     struct pci_device *dev);
0112
0113 int pci_device_get_bridge_buses(struct pci_device *dev, int *primary_bus,
0114     int *secondary_bus, int *subordinate_bus);
0115
0116 int pci_system_init(void);
0117
0118 void pci_system_init_dev_mem(int fd);
0119
0120 void pci_system_cleanup(void);
0121
0122 struct pci_device_iterator *pci_slot_match_iterator_create(
0123     const struct pci_slot_match *match);
0124
0125 struct pci_device_iterator *pci_id_match_iterator_create(
0126     const struct pci_id_match *match);
0127
0128 void pci_iterator_destroy(struct pci_device_iterator *iter);
0129
0130 struct pci_device *pci_device_next(struct pci_device_iterator *iter);
0131
0132 struct pci_device *pci_device_find_by_slot(uint32_t domain, uint32_t bus,
0133     uint32_t dev, uint32_t func);
0134
0135 struct pci_device *pci_device_get_parent_bridge(struct pci_device *dev);
0136
0137 void pci_get_strings(const struct pci_id_match *m,
0138     const char **device_name, const char **vendor_name,
0139     const char **subdevice_name, const char **subvendor_name);
0140 const char *pci_device_get_device_name(const struct pci_device *dev);
0141 const char *pci_device_get_subdevice_name(const struct pci_device *dev);
0142 const char *pci_device_get_vendor_name(const struct pci_device *dev);
0143 const char *pci_device_get_subvendor_name(const struct pci_device *dev);
0144
0145 void pci_device_enable(struct pci_device *dev);
0146 void pci_device_disable(struct pci_device *dev);
0147
0148 int pci_device_cfg_read    (struct pci_device *dev, void *data,
0149     pciaddr_t offset, pciaddr_t size, pciaddr_t *bytes_read);
0150 int pci_device_cfg_read_u8 (struct pci_device *dev, uint8_t  *data,
0151     pciaddr_t offset);
0152 int pci_device_cfg_read_u16(struct pci_device *dev, uint16_t *data,
0153     pciaddr_t offset);
0154 int pci_device_cfg_read_u32(struct pci_device *dev, uint32_t *data,
0155     pciaddr_t offset);
0156
0157 int pci_device_cfg_write    (struct pci_device *dev, const void *data,
0158     pciaddr_t offset, pciaddr_t size, pciaddr_t *bytes_written);
0159 int pci_device_cfg_write_u8 (struct pci_device *dev, uint8_t  data,
0160     pciaddr_t offset);
0161 int pci_device_cfg_write_u16(struct pci_device *dev, uint16_t data,
0162     pciaddr_t offset);
0163 int pci_device_cfg_write_u32(struct pci_device *dev, uint32_t data,
0164     pciaddr_t offset);
0165 int pci_device_cfg_write_bits(struct pci_device *dev, uint32_t mask,
0166     uint32_t data, pciaddr_t offset);
0167
0168 #ifdef __cplusplus
0169 }
0170 #endif
0171
0172 /**
0173  * \name Mapping flags passed to \c pci_device_map_range
0174  */
0175 /*@{*/
0176 #define PCI_DEV_MAP_FLAG_WRITABLE       (1U<<0)
0177 #define PCI_DEV_MAP_FLAG_WRITE_COMBINE  (1U<<1)
0178 #define PCI_DEV_MAP_FLAG_CACHABLE       (1U<<2)
0179 /*@}*/
0180
0181
0182 #define PCI_MATCH_ANY  (~0U)
0183
0184 /**
0185  * Compare two PCI ID values (either vendor or device).  This is used
0186  * internally to compare the fields of \c pci_id_match to the fields of
0187  * \c pci_device.
0188  */
0189 #define PCI_ID_COMPARE(a, b) \
0190     (((a) == PCI_MATCH_ANY) || ((a) == (b)))
0191
0192 /**
0193  */
0194 struct pci_id_match {
0195     /**
0196      * \name Device / vendor matching controls
0197      *
0198      * Control the search based on the device, vendor, subdevice, or subvendor
0199      * IDs.  Setting any of these fields to \c PCI_MATCH_ANY will cause the
0200      * field to not be used in the comparison.
0201      */
0202     /*@{*/
0203     uint32_t    vendor_id;
0204     uint32_t    device_id;
0205     uint32_t    subvendor_id;
0206     uint32_t    subdevice_id;
0207     /*@}*/
0208
0209
0210     /**
0211      * \name Device class matching controls
0212      *
0213      */
0214     /*@{*/
0215     uint32_t    device_class;
0216     uint32_t    device_class_mask;
0217     /*@}*/
0218
0219     intptr_t    match_data;
0220 };
0221
0222
0223 /**
0224  */
0225 struct pci_slot_match {
0226     /**
0227      * \name Device slot matching controls
0228      *
0229      * Control the search based on the domain, bus, slot, and function of
0230      * the device.  Setting any of these fields to \c PCI_MATCH_ANY will cause
0231      * the field to not be used in the comparison.
0232      */
0233     /*@{*/
0234     uint32_t    domain;
0235     uint32_t    bus;
0236     uint32_t    dev;
0237     uint32_t    func;
0238     /*@}*/
0239
0240     intptr_t    match_data;
0241 };
0242
0243 /**
0244  * BAR descriptor for a PCI device.
0245  */
0246 struct pci_mem_region {
0247     /**
0248      * When the region is mapped, this is the pointer to the memory.
0249      *
0250      * This field is \b only set when the deprecated \c pci_device_map_region
0251      * interface is used.  Use \c pci_device_map_range instead.
0252      *
0253      * \deprecated
0254      */
0255     void *memory;
0256
0257
0258     /**
0259      * Base physical address of the region within its bus / domain.
0260      *
0261      * \warning
0262      * This address is really only useful to other devices in the same
0263      * domain.  It's probably \b not the address applications will ever
0264      * use.
0265      *
0266      * \warning
0267      * Most (all?) platform back-ends leave this field unset.
0268      */
0269     pciaddr_t bus_addr;
0270
0271
0272     /**
0273      * Base physical address of the region from the CPU's point of view.
0274      *
0275      * This address is typically passed to \c pci_device_map_range to create
0276      * a mapping of the region to the CPU's virtual address space.
0277      */
0278     pciaddr_t base_addr;
0279
0280
0281     /**
0282      * Size, in bytes, of the region.
0283      */
0284     pciaddr_t size;
0285
0286
0287     /**
0288      * Is the region I/O ports or memory?
0289      */
0290     unsigned is_IO:1;
0291
0292     /**
0293      * Is the memory region prefetchable?
0294      *
0295      * \note
0296      * This can only be set if \c is_IO is not set.
0297      */
0298     unsigned is_prefetchable:1;
0299
0300
0301     /**
0302      * Is the memory at a 64-bit address?
0303      *
0304      * \note
0305      * This can only be set if \c is_IO is not set.
0306      */
0307     unsigned is_64:1;
0308 };
0309
0310
0311 /**
0312  * PCI device.
0313  *
0314  * Contains all of the information about a particular PCI device.
0315  *
0316  * This structure - like everything else in libpciaccess - is allocated
0317  * by the library itself. Do not embed this structure in other structs,
0318  * or otherwise allocate them yourself.
0319  */
0320 struct pci_device {
0321     /**
0322      * \name Device bus identification.
0323      *
0324      * Complete bus identification, including domain, of the device.  On
0325      * platforms that do not support PCI domains (e.g., 32-bit x86 hardware),
0326      * the domain will always be zero.
0327      *
0328      * The domain_16 field is provided for binary compatibility with older
0329      * libpciaccess.
0330      */
0331     /*@{*/
0332     uint16_t    domain_16;
0333     uint8_t     bus;
0334     uint8_t     dev;
0335     uint8_t     func;
0336     /*@}*/
0337
0338
0339     /**
0340      * \name Vendor / device ID
0341      *
0342      * The vendor ID, device ID, and sub-IDs for the device.
0343      */
0344     /*@{*/
0345     uint16_t    vendor_id;
0346     uint16_t    device_id;
0347     uint16_t    subvendor_id;
0348     uint16_t    subdevice_id;
0349     /*@}*/
0350
0351     /**
0352      * Device's class, subclass, and programming interface packed into a
0353      * single 32-bit value.  The class is at bits [23:16], subclass is at
0354      * bits [15:8], and programming interface is at [7:0].
0355      */
0356     uint32_t    device_class;
0357
0358
0359     /**
0360      * Device revision number, as read from the configuration header.
0361      */
0362     uint8_t     revision;
0363
0364
0365     /**
0366      * BAR descriptors for the device.
0367      */
0368     struct pci_mem_region regions[6];
0369
0370
0371     /**
0372      * Size, in bytes, of the device's expansion ROM.
0373      */
0374     pciaddr_t   rom_size;
0375
0376
0377     /**
0378      * IRQ associated with the device.  If there is no IRQ, this value will
0379      * be -1.
0380      */
0381     int irq;
0382
0383
0384     /**
0385      * Storage for user data.  Users of the library can store arbitrary
0386      * data in this pointer.  The library will not use it for any purpose.
0387      * It is the user's responsibility to free this memory before destroying
0388      * the \c pci_device structure.
0389      */
0390     intptr_t user_data;
0391
0392     /**
0393       * Used by the VGA arbiter. Type of resource decoded by the device and
0394       * the file descriptor (/dev/vga_arbiter). */
0395     int vgaarb_rsrc;
0396
0397
0398     /**
0399      * PCI domain value (full 32 bits)
0400      */
0401     uint32_t    domain;
0402 };
0403
0404
0405 /**
0406  * Description of the AGP capability of the device.
0407  *
0408  * \sa pci_device_get_agp_info
0409  */
0410 struct pci_agp_info {
0411     /**
0412      * Offset of the AGP registers in the devices configuration register
0413      * space.  This is generally used so that the offset of the AGP command
0414      * register can be determined.
0415      */
0416     unsigned    config_offset;
0417
0418
0419     /**
0420      * \name AGP major / minor version.
0421      */
0422     /*@{*/
0423     uint8_t major_version;
0424     uint8_t     minor_version;
0425     /*@}*/
0426
0427     /**
0428      * Logical OR of the supported AGP rates.  For example, a value of 0x07
0429      * means that the device can support 1x, 2x, and 4x.  A value of 0x0c
0430      * means that the device can support 8x and 4x.
0431      */
0432     uint8_t    rates;
0433
0434     unsigned int    fast_writes:1;  /**< Are fast-writes supported? */
0435     unsigned int    addr64:1;
0436     unsigned int    htrans:1;
0437     unsigned int    gart64:1;
0438     unsigned int    coherent:1;
0439     unsigned int    sideband:1;     /**< Is side-band addressing supported? */
0440     unsigned int    isochronus:1;
0441
0442     uint8_t    async_req_size;
0443     uint8_t    calibration_cycle_timing;
0444     uint8_t    max_requests;
0445 };
0446
0447 /**
0448  * Description of a PCI-to-PCI bridge device.
0449  *
0450  * \sa pci_device_get_bridge_info
0451  */
0452 struct pci_bridge_info {
0453     uint8_t    primary_bus;
0454     uint8_t    secondary_bus;
0455     uint8_t    subordinate_bus;
0456     uint8_t    secondary_latency_timer;
0457
0458     uint8_t     io_type;
0459     uint8_t     mem_type;
0460     uint8_t     prefetch_mem_type;
0461
0462     uint16_t    secondary_status;
0463     uint16_t    bridge_control;
0464
0465     uint32_t    io_base;
0466     uint32_t    io_limit;
0467
0468     uint32_t    mem_base;
0469     uint32_t    mem_limit;
0470
0471     uint64_t    prefetch_mem_base;
0472     uint64_t    prefetch_mem_limit;
0473 };
0474
0475 /**
0476  * Description of a PCI-to-PCMCIA bridge device.
0477  *
0478  * \sa pci_device_get_pcmcia_bridge_info
0479  */
0480 struct pci_pcmcia_bridge_info {
0481     uint8_t    primary_bus;
0482     uint8_t    card_bus;
0483     uint8_t    subordinate_bus;
0484     uint8_t    cardbus_latency_timer;
0485
0486     uint16_t    secondary_status;
0487     uint16_t    bridge_control;
0488
0489     struct {
0490     uint32_t    base;
0491     uint32_t    limit;
0492     } io[2];
0493
0494     struct {
0495     uint32_t    base;
0496     uint32_t    limit;
0497     } mem[2];
0498
0499 };
0500
0501
0502 /**
0503  * VGA Arbiter definitions, functions and related.
0504  */
0505
0506 /* Legacy VGA regions */
0507 #define VGA_ARB_RSRC_NONE       0x00
0508 #define VGA_ARB_RSRC_LEGACY_IO  0x01
0509 #define VGA_ARB_RSRC_LEGACY_MEM 0x02
0510 /* Non-legacy access */
0511 #define VGA_ARB_RSRC_NORMAL_IO  0x04
0512 #define VGA_ARB_RSRC_NORMAL_MEM 0x08
0513
0514 int  pci_device_vgaarb_init         (void);
0515 void pci_device_vgaarb_fini         (void);
0516 int  pci_device_vgaarb_set_target   (struct pci_device *dev);
0517 /* use the targeted device */
0518 int  pci_device_vgaarb_decodes      (int new_vga_rsrc);
0519 int  pci_device_vgaarb_lock         (void);
0520 int  pci_device_vgaarb_trylock      (void);
0521 int  pci_device_vgaarb_unlock       (void);
0522 /* return the current device count + resource decodes for the device */
0523 int pci_device_vgaarb_get_info      (struct pci_device *dev, int *vga_count, int *rsrc_decodes);
0524
0525 /*
0526  * I/O space access.
0527  */
0528
0529 struct pci_io_handle;
0530
0531 struct pci_io_handle *pci_device_open_io(struct pci_device *dev, pciaddr_t base,
0532                      pciaddr_t size);
0533 struct pci_io_handle *pci_legacy_open_io(struct pci_device *dev, pciaddr_t base,
0534                      pciaddr_t size);
0535 void pci_device_close_io(struct pci_device *dev, struct pci_io_handle *handle);
0536 uint32_t pci_io_read32(struct pci_io_handle *handle, uint32_t reg);
0537 uint16_t pci_io_read16(struct pci_io_handle *handle, uint32_t reg);
0538 uint8_t pci_io_read8(struct pci_io_handle *handle, uint32_t reg);
0539 void pci_io_write32(struct pci_io_handle *handle, uint32_t reg, uint32_t data);
0540 void pci_io_write16(struct pci_io_handle *handle, uint32_t reg, uint16_t data);
0541 void pci_io_write8(struct pci_io_handle *handle, uint32_t reg, uint8_t data);
0542
0543 /*
0544  * Legacy memory access
0545  */
0546
0547 int pci_device_map_legacy(struct pci_device *dev, pciaddr_t base,
0548               pciaddr_t size, unsigned map_flags, void **addr);
0549 int pci_device_unmap_legacy(struct pci_device *dev, void *addr, pciaddr_t size);
0550
0551 #endif /* PCIACCESS_H */