mirror of
https://gitlab.freedesktop.org/upower/upower.git
synced 2026-05-18 21:58:15 +02:00
339 lines
12 KiB
XML
339 lines
12 KiB
XML
<!DOCTYPE node PUBLIC
|
|
"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
|
|
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd" [
|
|
<!ENTITY ERROR_GENERAL "org.freedesktop.UPower.GeneralError">
|
|
]>
|
|
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
|
<interface name="org.freedesktop.UPower.QoS">
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
org.freedesktop.UPower.QoS is a DBus interface implimented
|
|
by UPower.
|
|
It allows applications to request latencies, for example a couple of seconds
|
|
for an IM application, or a few hundred microseconds for a multiplayer game.
|
|
</doc:para>
|
|
<doc:para>
|
|
Use cases:
|
|
</doc:para>
|
|
<doc:itemizedlist>
|
|
<doc:listitem>
|
|
<doc:para>
|
|
I want my IM application to request 0.5s latency for messages.
|
|
</doc:para>
|
|
<doc:para>
|
|
I'm running an OpenGL simulation and want maximum performance,
|
|
even when on battery power.
|
|
</doc:para>
|
|
<doc:para>
|
|
I'm running an SQL server for a credit card company, and want the
|
|
server to request low latency CPU and network as any delay costs money.
|
|
</doc:para>
|
|
<doc:para>
|
|
I'm an admin, and want to change the power consumption vs. latency
|
|
from cron scripts so it uses high latency during the night for
|
|
maximum power saving, and low latency during business hours.
|
|
</doc:para>
|
|
<doc:para>
|
|
I want high throughput when copying files, but want low throughput
|
|
for downloading updates in the background.
|
|
</doc:para>
|
|
<doc:para>
|
|
I want my power manager to set all latencies to lowest when on
|
|
AC power.
|
|
</doc:para>
|
|
<doc:para>
|
|
I don't want my users messing with latency settings.
|
|
</doc:para>
|
|
<doc:para>
|
|
I'm and admin and I want to be able to override all latency
|
|
settings on my machines.
|
|
</doc:para>
|
|
</doc:listitem>
|
|
</doc:itemizedlist>
|
|
<doc:para>
|
|
Why don't applications use the PMQoS interface directly?
|
|
By providing a framework we can override requests by policy, and also
|
|
control requests from random services.
|
|
You also can't set latencies unless you're the root user, which is not
|
|
suitable for the desktop use case.
|
|
</doc:para>
|
|
<doc:para>
|
|
Of course, you can do if you really want, but then you loose the
|
|
benefits of the query interface and the policy override,
|
|
and have to run your application as root.
|
|
</doc:para>
|
|
</doc:description>
|
|
</doc:doc>
|
|
|
|
<!-- ************************************************************ -->
|
|
<method name="SetMinimumLatency">
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="type" direction="in" type="s">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The type of latency to control, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="value" direction="in" type="i">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The value, in microseconds or kilobits per second.
|
|
The value <doc:tt>-1</doc:tt> means unset and the default is used.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Set the minimum acceptable latency of the system.
|
|
Setting this value tells the system to not attempt latencies below this setting.
|
|
This may be useful in a data center or server room, when you want to override the
|
|
latency requests from applications.
|
|
This may be required if the server room is operating outside a standard thermal
|
|
or power envelope, and an override is required.
|
|
You do not have to use this method during normal operation.
|
|
</doc:para>
|
|
</doc:description>
|
|
<doc:permission>Callers need the <doc:tt>org.freedesktop.upower.qos.set-minimum-latency</doc:tt> authorization</doc:permission>
|
|
<doc:errors>
|
|
<doc:error name="&ERROR_GENERAL;">if an error occured while setting the latency</doc:error>
|
|
</doc:errors>
|
|
</doc:doc>
|
|
</method>
|
|
|
|
<!-- ************************************************************ -->
|
|
<method name="RequestLatency">
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="type" direction="in" type="s">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The type of latency to control, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="value" direction="in" type="i">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The value, in microseconds or kilobits per second.
|
|
The value <doc:tt>-1</doc:tt> means remove all latency requirements.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="persistent" direction="in" type="b">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
If the latency request outlives the connection.
|
|
When the application issuing the request disconnects from the system
|
|
bus, the latency request is automatically cleaned up.
|
|
By setting this flag to TRUE, the request is not cleaned up when
|
|
the client disconnects, and the cookie is preserved acress reboots.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="cookie" direction="out" type="u">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
A cookie that identifies the request. This allows an application or
|
|
service to request multiple latency settings from one process, and for
|
|
other processes to cancel requests.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Set the required latency of an application or service.
|
|
</doc:para>
|
|
</doc:description>
|
|
<doc:permission>
|
|
Callers need the
|
|
<doc:tt>org.freedesktop.upower.qos.request-latency-persistent</doc:tt>
|
|
authorization if <doc:tt>persistent</doc:tt> is TRUE, or
|
|
<doc:tt>org.freedesktop.upower.qos.request-latency</doc:tt> otherwise.
|
|
</doc:permission>
|
|
<doc:errors>
|
|
<doc:error name="&ERROR_GENERAL;">if an error occured while setting the latency</doc:error>
|
|
</doc:errors>
|
|
</doc:doc>
|
|
</method>
|
|
|
|
<!-- ************************************************************ -->
|
|
<method name="CancelRequest">
|
|
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
|
|
<arg name="type" direction="in" type="s">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The type of latency to control, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="cookie" direction="in" type="u">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
A cookie that identifies the request. This allows an application or
|
|
serivice to request multiple latency settings from one process.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Cancel the latency request from the application or service.
|
|
</doc:para>
|
|
</doc:description>
|
|
<doc:permission>
|
|
Callers need the
|
|
<doc:tt>org.freedesktop.upower.qos.cancel-request</doc:tt>
|
|
authorization if they were not the one issuing the request.
|
|
</doc:permission>
|
|
<doc:errors>
|
|
<doc:error name="&ERROR_GENERAL;">if an error occured while clearing the latency</doc:error>
|
|
</doc:errors>
|
|
</doc:doc>
|
|
</method>
|
|
|
|
<!-- ************************************************************ -->
|
|
<method name="GetLatency">
|
|
<arg name="type" direction="in" type="s">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The type of latency to return, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="value" direction="out" type="i">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The value, in microseconds or kilobits per second.
|
|
The value <doc:tt>-1</doc:tt> means not set or unavailable.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Get the lowest latency state on the system at the current time.
|
|
</doc:para>
|
|
</doc:description>
|
|
<doc:errors>
|
|
<doc:error name="&ERROR_GENERAL;">if an error occured while getting the latency</doc:error>
|
|
</doc:errors>
|
|
</doc:doc>
|
|
</method>
|
|
|
|
<!-- ************************************************************ -->
|
|
<signal name="LatencyChanged">
|
|
<arg name="type" direction="out" type="s">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The type of latency that changed, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<arg name="value" direction="out" type="i">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The value, in microseconds or kilobits per second.
|
|
The value <doc:tt>-1</doc:tt> means not set or unavailable.
|
|
</doc:summary>
|
|
</doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Some latency value has changed.
|
|
</doc:para>
|
|
</doc:description>
|
|
</doc:doc>
|
|
</signal>
|
|
|
|
<!-- ************************************************************ -->
|
|
<method name="GetLatencyRequests">
|
|
<arg name="requests" direction="out" type="a(uuusxbssi)">
|
|
<doc:doc>
|
|
<doc:summary>
|
|
The request lists, where each application can request different
|
|
latency types.
|
|
<doc:list>
|
|
<doc:item>
|
|
<doc:term>cookie</doc:term>
|
|
<doc:definition>
|
|
The random cookie that identifies the request.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>uid</doc:term>
|
|
<doc:definition>
|
|
The user ID that issued the request.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>pid</doc:term>
|
|
<doc:definition>
|
|
The process ID of the application.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>exec</doc:term>
|
|
<doc:definition>
|
|
The executable that issued the request.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>timespec</doc:term>
|
|
<doc:definition>
|
|
The number of seconds since the epoch.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>persistent</doc:term>
|
|
<doc:definition>
|
|
If the request is persistent and outlives the connection lifetime.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>type</doc:term>
|
|
<doc:definition>
|
|
The type of the request, <doc:tt>cpu_dma</doc:tt> or
|
|
<doc:tt>network</doc:tt>.
|
|
</doc:definition>
|
|
</doc:item>
|
|
<doc:item>
|
|
<doc:term>value</doc:term>
|
|
<doc:definition>
|
|
The value, in microseconds or kilobits per second.
|
|
</doc:definition>
|
|
</doc:item>
|
|
</doc:list>
|
|
</doc:summary></doc:doc>
|
|
</arg>
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
Gets all the system requests from all services and applications.
|
|
</doc:para>
|
|
</doc:description>
|
|
</doc:doc>
|
|
</method>
|
|
|
|
<!-- ************************************************************ -->
|
|
<signal name="RequestsChanged">
|
|
<doc:doc>
|
|
<doc:description>
|
|
<doc:para>
|
|
The latency requests on the system have changed.
|
|
</doc:para>
|
|
</doc:description>
|
|
</doc:doc>
|
|
</signal>
|
|
|
|
</interface>
|
|
|
|
</node>
|