summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorRichard Hughes <richard@hughsie.com>2008-11-13 16:39:57 +0000
committerRichard Hughes <richard@hughsie.com>2008-11-13 16:39:57 +0000
commitd891912126a45a22184c694781830e8f8c90f014 (patch)
tree0b023899af711b50e05666b863acaeac2471833a /src
parent3d232b8066cc71728326971c351406c7e8022d90 (diff)
feature: add in the interface file for QoS control
Diffstat (limited to 'src')
-rw-r--r--src/Makefile.am13
-rw-r--r--src/org.freedesktop.DeviceKit.Power.QoS.xml341
2 files changed, 352 insertions, 2 deletions
diff --git a/src/Makefile.am b/src/Makefile.am
index 4d501d7..7d7c2b4 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -26,7 +26,9 @@ DEVKIT_POWER_LIBS = $(top_builddir)/libdevkit-power/libdevkit-power.la
BUILT_SOURCES = \
dkp-daemon-glue.h \
dkp-device-glue.h \
- dkp-marshal.h dkp-marshal.c
+ dkp-qos-glue.h \
+ dkp-marshal.h \
+ dkp-marshal.c
dkp-marshal.h: dkp-marshal.list
glib-genmarshal $< --prefix=dkp_marshal --header > $@
@@ -40,10 +42,16 @@ dkp-daemon-glue.h: org.freedesktop.DeviceKit.Power.xml Makefile.am
dkp-device-glue.h: org.freedesktop.DeviceKit.Power.Device.xml Makefile.am
dbus-binding-tool --prefix=dkp_device --mode=glib-server --output=dkp-device-glue.h org.freedesktop.DeviceKit.Power.Device.xml
+dkp-qos-glue.h: org.freedesktop.DeviceKit.Power.QoS.xml Makefile.am
+ dbus-binding-tool --prefix=dkp_qos --mode=glib-server --output=dkp-qos-glue.h org.freedesktop.DeviceKit.Power.QoS.xml
+
libexec_PROGRAMS = devkit-power-daemon
dbusifdir = $(datadir)/dbus-1/interfaces
-dbusif_DATA = org.freedesktop.DeviceKit.Power.xml org.freedesktop.DeviceKit.Power.Device.xml
+dbusif_DATA = \
+ org.freedesktop.DeviceKit.Power.xml \
+ org.freedesktop.DeviceKit.Power.Device.xml \
+ org.freedesktop.DeviceKit.Power.QoS.xml
devkit_power_daemon_SOURCES = \
egg-debug.c \
@@ -103,6 +111,7 @@ CLEANFILES = $(BUILT_SOURCES)
EXTRA_DIST = \
org.freedesktop.DeviceKit.Power.xml \
org.freedesktop.DeviceKit.Power.Device.xml \
+ org.freedesktop.DeviceKit.Power.QoS.xml \
dkp-marshal.list \
95-devkit-power-csr.rules \
95-devkit-power-hid.rules \
diff --git a/src/org.freedesktop.DeviceKit.Power.QoS.xml b/src/org.freedesktop.DeviceKit.Power.QoS.xml
new file mode 100644
index 0000000..47341ba
--- /dev/null
+++ b/src/org.freedesktop.DeviceKit.Power.QoS.xml
@@ -0,0 +1,341 @@
+<!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.DeviceKit.Power.GeneralError">
+]>
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+ <interface name="org.freedesktop.DeviceKit.Power.QoS">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ org.freedesktop.DeviceKit.Power.QoS is a DBus interface implimented
+ by DeviceKit-power.
+ 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.devicekit.power.latency.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.devicekit.power.latency.request-latency-persistent</doc:tt>
+ authorization if <doc:tt>persistent</doc:tt> is TRUE, or
+ <doc:tt>org.freedesktop.devicekit.power.latency.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.devicekit.power.latency.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">
+ <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+ <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:tt>discharging</doc:tt>.
+ </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>