26ec4e53f2
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.
Make the doc comments more strongly consistent about indentation
for multiline constructs like:
@arg: description line 1
description line 2
Returns: line one
line 2
so that there is always exactly one space after the colon, and
subsequent lines align with the first.
This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace). This does mean that we end up with some
over-length lines.
Note that when the documentation for an argument fits on a single
line like this:
@arg: one line only
then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
108 lines
2.8 KiB
Python
108 lines
2.8 KiB
Python
# -*- mode: 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" } ] }
|
|
#
|
|
##
|
|
{ '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'} }
|