# -*- Mode: Python -*-
# vim: filetype=python
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.
# SPDX-License-Identifier: GPL-2.0-or-later

##
# = PCI
##

##
# @PciMemoryRange:
#
# A PCI device memory region
#
# @base: the starting address (guest physical)
#
# @limit: the ending address (guest physical)
#
# Since: 0.14
##
{ 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }

##
# @PciMemoryRegion:
#
# Information about a PCI device I/O region.
#
# @bar: the index of the Base Address Register for this region
#
# @type:
#     - 'io' if the region is a PIO region
#     - 'memory' if the region is a MMIO region
#
# @size: memory size
#
# @prefetch: if @type is 'memory', true if the memory is prefetchable
#
# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
#
# Since: 0.14
##
{ 'struct': 'PciMemoryRegion',
  'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
           '*prefetch': 'bool', '*mem_type_64': 'bool' } }

##
# @PciBusInfo:
#
# Information about a bus of a PCI Bridge device
#
# @number: primary bus interface number.  This should be the number of
#     the bus the device resides on.
#
# @secondary: secondary bus interface number.  This is the number of
#     the main bus for the bridge
#
# @subordinate: This is the highest number bus that resides below the
#     bridge.
#
# @io_range: The PIO range for all devices on this bridge
#
# @memory_range: The MMIO range for all devices on this bridge
#
# @prefetchable_range: The range of prefetchable MMIO for all devices
#     on this bridge
#
# Since: 2.4
##
{ 'struct': 'PciBusInfo',
  'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
           'io_range': 'PciMemoryRange',
           'memory_range': 'PciMemoryRange',
           'prefetchable_range': 'PciMemoryRange' } }

##
# @PciBridgeInfo:
#
# Information about a PCI Bridge device
#
# @bus: information about the bus the device resides on
#
# @devices: a list of @PciDeviceInfo for each device on this bridge
#
# Since: 0.14
##
{ 'struct': 'PciBridgeInfo',
  'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }

##
# @PciDeviceClass:
#
# Information about the Class of a PCI device
#
# @desc: a string description of the device's class
#
# @class: the class code of the device
#
# Since: 2.4
##
{ 'struct': 'PciDeviceClass',
  'data': {'*desc': 'str', 'class': 'int'} }

##
# @PciDeviceId:
#
# Information about the Id of a PCI device
#
# @device: the PCI device id
#
# @vendor: the PCI vendor id
#
# @subsystem: the PCI subsystem id (since 3.1)
#
# @subsystem-vendor: the PCI subsystem vendor id (since 3.1)
#
# Since: 2.4
##
{ 'struct': 'PciDeviceId',
  'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int',
            '*subsystem-vendor': 'int'} }

##
# @PciDeviceInfo:
#
# Information about a PCI device
#
# @bus: the bus number of the device
#
# @slot: the slot the device is located in
#
# @function: the function of the slot used by the device
#
# @class_info: the class of the device
#
# @id: the PCI device id
#
# @irq: if an IRQ is assigned to the device, the IRQ number
#
# @irq_pin: the IRQ pin, zero means no IRQ (since 5.1)
#
# @qdev_id: the device name of the PCI device
#
# @pci_bridge: if the device is a PCI bridge, the bridge information
#
# @regions: a list of the PCI I/O regions associated with the device
#
# Notes: the contents of @class_info.desc are not stable and should
#     only be treated as informational.
#
# Since: 0.14
##
{ 'struct': 'PciDeviceInfo',
  'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
           'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
           '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str',
           '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }}

##
# @PciInfo:
#
# Information about a PCI bus
#
# @bus: the bus index
#
# @devices: a list of devices on this bus
#
# Since: 0.14
##
{ 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }

##
# @query-pci:
#
# Return information about the PCI bus topology of the guest.
#
# Returns: a list of @PciInfo for each PCI bus.  Each bus is
#     represented by a json-object, which has a key with a json-array
#     of all PCI devices attached to it.  Each device is represented
#     by a json-object.
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "query-pci" }
# <- { "return": [
#          {
#             "bus": 0,
#             "devices": [
#                {
#                   "bus": 0,
#                   "qdev_id": "",
#                   "slot": 0,
#                   "class_info": {
#                      "class": 1536,
#                      "desc": "Host bridge"
#                   },
#                   "id": {
#                      "device": 32902,
#                      "vendor": 4663
#                   },
#                   "function": 0,
#                   "regions": [
#                   ]
#                },
#                {
#                   "bus": 0,
#                   "qdev_id": "",
#                   "slot": 1,
#                   "class_info": {
#                      "class": 1537,
#                      "desc": "ISA bridge"
#                   },
#                   "id": {
#                      "device": 32902,
#                      "vendor": 28672
#                   },
#                   "function": 0,
#                   "regions": [
#                   ]
#                },
#                {
#                   "bus": 0,
#                   "qdev_id": "",
#                   "slot": 1,
#                   "class_info": {
#                      "class": 257,
#                      "desc": "IDE controller"
#                   },
#                   "id": {
#                      "device": 32902,
#                      "vendor": 28688
#                   },
#                   "function": 1,
#                   "regions": [
#                      {
#                         "bar": 4,
#                         "size": 16,
#                         "address": 49152,
#                         "type": "io"
#                      }
#                   ]
#                },
#                {
#                   "bus": 0,
#                   "qdev_id": "",
#                   "slot": 2,
#                   "class_info": {
#                      "class": 768,
#                      "desc": "VGA controller"
#                   },
#                   "id": {
#                      "device": 4115,
#                      "vendor": 184
#                   },
#                   "function": 0,
#                   "regions": [
#                      {
#                         "prefetch": true,
#                         "mem_type_64": false,
#                         "bar": 0,
#                         "size": 33554432,
#                         "address": 4026531840,
#                         "type": "memory"
#                      },
#                      {
#                         "prefetch": false,
#                         "mem_type_64": false,
#                         "bar": 1,
#                         "size": 4096,
#                         "address": 4060086272,
#                         "type": "memory"
#                      },
#                      {
#                         "prefetch": false,
#                         "mem_type_64": false,
#                         "bar": 6,
#                         "size": 65536,
#                         "address": -1,
#                         "type": "memory"
#                      }
#                   ]
#                },
#                {
#                   "bus": 0,
#                   "qdev_id": "",
#                   "irq": 11,
#                   "slot": 4,
#                   "class_info": {
#                      "class": 1280,
#                      "desc": "RAM controller"
#                   },
#                   "id": {
#                      "device": 6900,
#                      "vendor": 4098
#                   },
#                   "function": 0,
#                   "regions": [
#                      {
#                         "bar": 0,
#                         "size": 32,
#                         "address": 49280,
#                         "type": "io"
#                      }
#                   ]
#                }
#             ]
#          }
#       ]
#    }
#
# Note: This example has been shortened as the real response is too
#     long.
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }