c110102898
Peter Maydell's commit100cc4fe0fexplains: rST insists on a blank line before and after a bulleted list [...] Add some extra blank lines in the doc comments so they're acceptable rST input. It missed one in qapi/trace.json. Paolo Bonzini later added another instance in qapi/stats.json, providing further, if unintended, evidence for his quip that rST is the Perl of ASCII-based markups. Both are parsed as ordinary paragraph, resulting in garbled output. John Snow missed the need for a blank line when converting docs/devel/qapi-code-gen.txt to rST. Add the blank lines we need to get the bullet lists recognized as such. Kevin Wolf and Lukas Straub added two more, but indented. Sphinx recognizes them as (indented) bullet lists. The indentation looks slightly off. Insert a blank line and delete the extra indentation. Fixes:100cc4fe0f(qapi: Add blank lines before bulleted lists) Fixes:467ef823d8(qmp: add filtering of statistics by target vCPU) Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230425064223.820979-10-armbru@redhat.com> [Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted]
111 lines
2.9 KiB
Python
111 lines
2.9 KiB
Python
# -*- mode: python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Copyright (C) 2011-2016 Lluís Vilanova <vilanova@ac.upc.edu>
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
##
|
|
# = Tracing
|
|
##
|
|
|
|
##
|
|
# @TraceEventState:
|
|
#
|
|
# State of a tracing event.
|
|
#
|
|
# @unavailable: The event is statically disabled.
|
|
#
|
|
# @disabled: The event is dynamically disabled.
|
|
#
|
|
# @enabled: The event is dynamically enabled.
|
|
#
|
|
# Since: 2.2
|
|
##
|
|
{ 'enum': 'TraceEventState',
|
|
'data': ['unavailable', 'disabled', 'enabled'] }
|
|
|
|
##
|
|
# @TraceEventInfo:
|
|
#
|
|
# Information of a tracing event.
|
|
#
|
|
# @name: Event name.
|
|
# @state: Tracing state.
|
|
# @vcpu: Whether this is a per-vCPU event (since 2.7).
|
|
#
|
|
# An event is per-vCPU if it has the "vcpu" property in the "trace-events"
|
|
# files.
|
|
#
|
|
# Since: 2.2
|
|
##
|
|
{ 'struct': 'TraceEventInfo',
|
|
'data': {'name': 'str', 'state': 'TraceEventState', 'vcpu': 'bool'} }
|
|
|
|
##
|
|
# @trace-event-get-state:
|
|
#
|
|
# Query the state of events.
|
|
#
|
|
# @name: Event name pattern (case-sensitive glob).
|
|
# @vcpu: The vCPU to query (any by default; since 2.7).
|
|
#
|
|
# Returns: a list of @TraceEventInfo for the matching events
|
|
#
|
|
# An event is returned if:
|
|
#
|
|
# - its name matches the @name pattern, and
|
|
# - if @vcpu is given, the event has the "vcpu" property.
|
|
#
|
|
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
|
|
# returning their state on the specified vCPU. Special case: if @name is an
|
|
# exact match, @vcpu is given and the event does not have the "vcpu" property,
|
|
# an error is returned.
|
|
#
|
|
# Since: 2.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "trace-event-get-state",
|
|
# "arguments": { "name": "qemu_memalign" } }
|
|
# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
|
|
#
|
|
##
|
|
{ 'command': 'trace-event-get-state',
|
|
'data': {'name': 'str', '*vcpu': 'int'},
|
|
'returns': ['TraceEventInfo'] }
|
|
|
|
##
|
|
# @trace-event-set-state:
|
|
#
|
|
# Set the dynamic tracing state of events.
|
|
#
|
|
# @name: Event name pattern (case-sensitive glob).
|
|
# @enable: Whether to enable tracing.
|
|
# @ignore-unavailable: Do not match unavailable events with @name.
|
|
# @vcpu: The vCPU to act upon (all by default; since 2.7).
|
|
#
|
|
# An event's state is modified if:
|
|
#
|
|
# - its name matches the @name pattern, and
|
|
# - if @vcpu is given, the event has the "vcpu" property.
|
|
#
|
|
# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
|
|
# setting their state on the specified vCPU. Special case: if @name is an exact
|
|
# match, @vcpu is given and the event does not have the "vcpu" property, an
|
|
# error is returned.
|
|
#
|
|
# Since: 2.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "trace-event-set-state",
|
|
# "arguments": { "name": "qemu_memalign", "enable": true } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'trace-event-set-state',
|
|
'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool',
|
|
'*vcpu': 'int'} }
|