diff options
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/dbus/Makefile.am | 6 | ||||
-rw-r--r-- | doc/devkit-power-docs.xml | 1 | ||||
-rw-r--r-- | policy/org.freedesktop.devicekit.power.policy.in | 40 | ||||
-rw-r--r-- | src/Makefile.am | 13 | ||||
-rw-r--r-- | src/org.freedesktop.DeviceKit.Power.QoS.xml | 341 |
6 files changed, 399 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 5d5a83f..94b5b23 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -54,6 +54,7 @@ content_files = \ man/DeviceKit-power.xml \ dbus/org.freedesktop.DeviceKit.Power.ref.xml \ dbus/org.freedesktop.DeviceKit.Power.Device.ref.xml \ + dbus/org.freedesktop.DeviceKit.Power.QoS.ref.xml \ $(NULL) # Images to copy into HTML directory diff --git a/doc/dbus/Makefile.am b/doc/dbus/Makefile.am index c8511ac..6ac027d 100644 --- a/doc/dbus/Makefile.am +++ b/doc/dbus/Makefile.am @@ -1,5 +1,5 @@ -all : org.freedesktop.DeviceKit.Power.ref.xml org.freedesktop.DeviceKit.Power.Device.ref.xml +all : org.freedesktop.DeviceKit.Power.ref.xml org.freedesktop.DeviceKit.Power.Device.ref.xml org.freedesktop.DeviceKit.Power.QoS.ref.xml org.freedesktop.DeviceKit.Power.ref.xml : $(top_srcdir)/src/org.freedesktop.DeviceKit.Power.xml $(top_srcdir)/doc/dbus/spec-to-docbook.xsl echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ @@ -9,6 +9,10 @@ org.freedesktop.DeviceKit.Power.Device.ref.xml : $(top_srcdir)/src/org.freedeskt echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ $(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@ +org.freedesktop.DeviceKit.Power.QoS.ref.xml : $(top_srcdir)/src/org.freedesktop.DeviceKit.Power.QoS.xml $(top_srcdir)/doc/dbus/spec-to-docbook.xsl + echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@ + $(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@ + EXTRA_DIST = spec-to-docbook.xsl dbus-introspect-docs.dtd clean-local : diff --git a/doc/devkit-power-docs.xml b/doc/devkit-power-docs.xml index 3cfcae2..c052b6b 100644 --- a/doc/devkit-power-docs.xml +++ b/doc/devkit-power-docs.xml @@ -66,6 +66,7 @@ </partintro> <xi:include href="dbus/org.freedesktop.DeviceKit.Power.ref.xml"/> <xi:include href="dbus/org.freedesktop.DeviceKit.Power.Device.ref.xml"/> + <xi:include href="dbus/org.freedesktop.DeviceKit.Power.QoS.ref.xml"/> </reference> <reference id="tools-fileformats"> diff --git a/policy/org.freedesktop.devicekit.power.policy.in b/policy/org.freedesktop.devicekit.power.policy.in index d74e16c..3185c97 100644 --- a/policy/org.freedesktop.devicekit.power.policy.in +++ b/policy/org.freedesktop.devicekit.power.policy.in @@ -39,4 +39,44 @@ file are instantly applied. </defaults> </action> + <action id="org.freedesktop.devicekit.power.latency.request-latency"> + <_description>Set the required latency of an application</_description> + <_message>Authentication is required to set the required latency of an application</_message> + <defaults> + <allow_any>no</allow_any> + <allow_inactive>no</allow_inactive> + <allow_active>yes</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.devicekit.power.latency.request-latency-persistent"> + <_description>Set a persistent latency setting</_description> + <_message>Authentication is required to set a persistent latency setting</_message> + <defaults> + <allow_any>no</allow_any> + <allow_inactive>no</allow_inactive> + <allow_active>yes</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.devicekit.power.latency.set-minimum-latency"> + <_description>Set administrator settings for latency control</_description> + <_message>Authentication is required to set administrator settings for latency control</_message> + <defaults> + <allow_any>no</allow_any> + <allow_inactive>no</allow_inactive> + <allow_active>auth_admin</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.devicekit.power.latency.cancel-request"> + <_description>Cancel a latency request</_description> + <_message>Authentication is required to cancel a latency request</_message> + <defaults> + <allow_any>no</allow_any> + <allow_inactive>no</allow_inactive> + <allow_active>auth_admin</allow_active> + </defaults> + </action> + </policyconfig> 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> |