# -*- 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
#
# .. note:: 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"
#                          }
#                       ]
#                    }
#                 ]
#              }
#           ]
#        }
#
# This example has been shortened as the real response is too long.
#
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }