Tuesday, September 8, 2009

Convergence 09: Developing Power Aware Application using D-Bus

Introduction


Computer power consumption has become a passionate subject; hardware engineers trying to minimize the power consumed by devices, and software engineers trying to optimize their code to reduce the power consumed by their applications. Power is an even more important issue with Mobile Internet Devices (MIDs) since the small form factor limits the size of the battery. Applications running on MID's must therefore be very sensitive to power, and use power information to make smart decisions. For example, before beginning a lengthy transaction (such as downloading a video, or running an update), an application should check to see if the device is running on external power, and if not, determine whether or not there is sufficient power remaining to complete the transaction.

Background on D-Bus

D-Bus is a fast, lightweight message bus system which allows applications to communicate each other (Inter-process communication) [2]. It has a so-called D-Bus message bus (dbus deamon) which can accept messages from multiples applications and forward messages to them. D-Bus can be used as low-level API or higher level binding, such as Qt, Python*, Java*, C#, or Perl. This paper shows an application written in C using Glib bindings. Glib is the base library of GNOME, it provides an object system, object-based and event-driven programming.

Two buses are defined in D-Bus: system bus and session bus. The system bus allows communication between an application and the operating system while the session bus is designed to serve the communication between two applications.

In order to use D-Bus, we need to explore some concepts about D-Bus. First, an object is an endpoint on the bus, an object is created by an application in the context that the application's connection to the bus (either system bus or session bus). Objects have names, and these names are called object paths. A proxy is an object on the bus that can be accessed through references. We can find an object by searching the bus name and the object living in that bus connection. Once we find it, we usually keep a proxy to that object so we can refer to that object again without searching again.

An object can perform some specific operations. Each operation is referred as method. Thus, a client can send a request to an object and ask the object to invoke a method. The object then executes the method (if the method exists) and the result is sent back to the client. If a method requires input parameters, these parameters have to be passed with the request. The result can be one or more output parameters, these parameters are sent back to the client in the reply message.

An object can also emit an event, or signal. When a signal is generated by an object, it will be broadcasted to any observers who are interested in that particular signal. Signals can carry parameters too. Methods and Signals are embedded members of an object. They can be grouped. An Interface of an object is just a group of its members. An object can declare one or many interfaces - its members are then classified in these interfaces.

Instead of forming a D-Bus method call message and sending to the remote object using Glib bindings, one can instantiate a proxy object representing the remote object and then just invoke the methods of that object.

In order to generate dbus-glib binding code, we can use a tool called dbus-binding-tool. We first create an XML file, referred as Introspection XML file, in which we describe the methods and signals. An example of the introspection XML is shown below:

  1. "1.0" encoding="UTF-8" ?>

  3. "-//freedesktop//DTD D-Bus Object Introspection 1.0//EN"
  4. "http://standards.freedesktop.org/dbus/1.0/introspect.dtd">
  5. "/org/moblin/Platform">
  6. "org.moblin.Platform.Power">
  7. "org.freedesktop.DBus.GLib.CSymbol" value="org_moblin_platform_power"/>
  8. "IsUsingExternalPowerSource">
  9. "org.freedesktop.DBus.GLib.CSymbol" value="isUsingExternalPowerSource" />
  10. "b" name="usingExternalPowerSource" direction="out" />

  12. "GetTimeRemaining">
  13. "org.freedesktop.DBus.GLib.CSymbol" value="getTimeRemaining"/>
  14. "i" name="minutesRemaining" direction="out" />

  16. "GetPercentRemaining">
  17. "org.freedesktop.DBus.GLib.CSymbol" value="getPercentRemaining"/>
  18. "u" name="percentRemaining" direction="out" />





In this introspection XML file (named MIDPlatformSvcInterfaceDefinition.xml), an interface called org.moblin.Platform.Power defines three methods: IsUsingExternalPowerSource, GetTimeRemaining and GetPerCentRemaining. The output of the first method is a Boolean value. The output of the second method is an integer value representing the value in minutes, while the output of the third method is an unsigned integer value representing the percentage.

Below are primary steps to implement a service with methods to be exposed. More details are explained in [3].
  • Run dbus-binding-tool for an introspection XML file to generate dbus-glib binding code
  • Create a simple GObject for D-Bus
  • Implement the instance initialization
  • Implement the methods
  • Register the object to the D-Bus
To call the methods implemented on a remote object, a client needs to follow the following steps:
  • Connect to the bus
  • Create a proxy object
  • Invoke the methods on the proxy object

Using D-Bus as a Communication Channel


We designed the power service application which uses D-Bus as a communication channel to send information on battery. Other applications which are interested in power awareness can use D-Bus to get power information by querying the methods that the power service provided. These applications can also listen for the events that the power service generated. Figure 1 illustrates the usage model:

Figure 1. Usage Model: A Client Registers to D-Bus to Get the Information Provided by the MISPlatformSvc



Gathering Battery Information


We will present the implementation of three methods that are part of a simple library that provides battery information. The first method queries the percent of battery power remaining (getPercentRemaining). This method returns the percent of power currently available in the battery.

The second method queries the time remaining until the MID runs out of battery power (getTimeRemaining). This method returns the remaining time in minutes.

The third method queries whether or not the MID is using an external power source (IsUsingExternalPowerSource). This method returns a Boolean: TRUE means the MID is currently using an external power source (e.g., AC), FALSE means that the MID is using its battery (DC).

The first method calculates the percent of battery power remaining in a MID. In Linux, the file /proc/acpi/ contains power-related information. In particular, the file /proc/acpi/battery/BAT1/state contains the current remaining capacity in the field "remaining capacity". The file /proc/acpi/battery/BAT1/info contains the maximum capacity information in the "last full capacity" field. From these entries, we can deduce the percent of power remaining as shown below:

  1. gboolean computePercentPowerRemaining(guint *result)
  2. {
  3. DIR *d;
  4. struct dirent *de;
  5. char *acpi_path = "/proc/acpi";
  6. char *device_type = "battery";
  7. char *stateFile = "state";
  8. char *infoFile = "info";
  9. FILE *file;
  10. char filename[PATH_LENGTH];
  11. char line[LINE_LENGTH];
  12. *result = 0;
  13. double power_left = 0.0;
  14. double power_full = 0.0;
  15. gboolean rc = FALSE;

  17. // First, check if the ACPI path exists
  18. if (chdir(acpi_path) <>
  19. {
  20. dbg("ACPI is not supported (\"%s\").\n", acpi_path);
  21. return rc;
  22. }
  23. else
  24. dbg("Path %s is found \n", acpi_path);

  26. // Check if battery directory exists
  27. if (chdir(device_type) <>
  28. {
  29. dbg("No support for device type: %s\n", device_type);
  30. return rc;
  31. }
  32. else
  33. dbg("Device %s is supported \n", device_type);

  35. // /proc/acpi/battery is found. Now search for available batteries
  36. d = opendir(".");
  37. if (!d) {
  38. dbg("Cannot open directory!\n");
  39. return rc;
  40. }

  42. while ((de = readdir(d))) {
  43. // Search for real directory ("BAT0", ...), not ".", ".."
  44. if (!strcmp(de->d_name, "."))
  45. continue;

  47. if (!strcmp(de->d_name, ".."))
  48. continue;

  50. dbg("device found: %s\n", de->d_name);

  52. // Open file "state".
  53. sprintf(filename, "%s/%s/%s/%s", acpi_path, device_type, de->d_name, stateFile);
  54. file = fopen(filename, "r");
  55. if (!file)
  56. {
  57. closedir(d);
  58. return rc;
  59. }

  61. memset(line, 0, LINE_LENGTH);
  62. while (fgets(line, LINE_LENGTH, file) != NULL) {
  63. if (strstr(line, "remaining capacity:") &&
  64. (strstr(line, "mWh") || strstr(line, "mAh")))
  65. {
  66. // Search the value
  67. char *c;

  69. c = strchr(line, ':');
  70. c++;

  72. power_left = strtoull(c, NULL, 10); // in mWh or mAh

  74. // Cannot perform conversion
  75. if ((0 == power_left) && (EINVAL == errno))
  76. {
  77. closedir(d);
  78. return rc;
  79. }
  80. break;
  81. }
  82. }

  84. fclose(file);

  86. // Open file "info".
  87. sprintf(filename, "%s/%s/%s/%s", acpi_path, device_type, de->d_name, infoFile);
  88. file = fopen(filename, "r");
  89. if (!file)
  90. {
  91. closedir(d);
  92. return rc;
  93. }

  95. memset(line, 0, LINE_LENGTH);
  96. while (fgets(line, LINE_LENGTH, file) != NULL) {
  97. if (strstr(line, "last full capacity:") &&
  98. (strstr(line, "mWh") || strstr(line, "mAh")))
  99. {
  100. // Search the value
  101. char *c;

  103. c = strchr(line, ':');
  104. c++;

  106. power_full = strtoull(c, NULL, 10); // in mWh or mAh

  108. // Cannot perform conversion
  109. if (0 == power_full)
  110. {
  111. closedir(d);
  112. return rc;
  113. }

  115. *result = (power_left/power_full)*100; // in %
  116. break;
  117. }
  118. }

  120. rc = TRUE;
  121. fclose(file);

  123. // Exit while loop
  124. break;
  125. }
  126. closedir(d);

  128. return rc;
  129. }


The second method queries the time remaining until the MID is out battery power (getTimeRemaining). This method returns the remaining time in minutes. As mentioned above, the file /proc/acpi/battery/BAT1/state contains the current remaining capacity in the "remaining capacity" field. The "present rate" field in the same file contains the rate at which the battery capacity is changing. This field is significant only if the battery is discharging. From this information, we can deduce the remaining time in minutes as shown below:

- collapse sourceview plaincopy to clipboardprint?
  1. int computeTimeRemaining(void)
  2. {
  3. DIR *d;
  4. struct dirent *de;

  6. char *acpi_path = "/proc/acpi";
  7. char *device_type = "battery";
  8. char *stateFile = "state";

  10. FILE *file;
  11. char filename[PATH_LENGTH];
  12. char line[LINE_LENGTH];
  13. int result = -1;
  14. double power_left = 0.0;
  15. double power_full = 0.0;
  16. double dischargeRate = 0.0;
  17. int find = 0;

  19. // First, check if the ACPI path exists
  20. if (chdir(acpi_path) <>
  21. {
  22. dbg("ACPI is not supported (\"%s\").\n", acpi_path);
  23. return result;
  24. }
  25. else
  26. dbg("Path %s is found \n", acpi_path);

  28. // Check if battery directory exists
  29. if (chdir(device_type) <>
  30. {
  31. dbg("No support for device type: %s\n", device_type);
  32. return result;
  33. }
  34. else
  35. dbg("Device %s is supported \n", device_type);

  37. // /proc/acpi/battery is found. Now search for available batteries
  38. d = opendir(".");
  39. if (!d) {
  40. dbg("Cannot open directory!\n");
  41. return result;
  42. }

  44. while ((de = readdir(d))) {
  45. // Search for real directory ("BAT0", ...), not ".", ".."
  46. if (!strcmp(de->d_name, "."))
  47. continue;

  49. if (!strcmp(de->d_name, ".."))
  50. continue;

  52. dbg("device found: %s\n", de->d_name);

  54. // Open file "state".
  55. sprintf(filename, "%s/%s/%s/%s", acpi_path, device_type, de->d_name, stateFile);
  56. file = fopen(filename, "r");
  57. if (!file)
  58. {
  59. closedir(d);
  60. return result;
  61. }

  63. memset(line, 0, LINE_LENGTH);

  65. while (fgets(line, LINE_LENGTH, file) != NULL) {
  66. if (strstr(line, "charging state:") &&
  67. strstr(line, "discharging"))
  68. {
  69. find++;
  70. }

  72. if (strstr(line, "present rate:") &&
  73. (strstr(line, "mW") || strstr(line, "mA")))
  74. {
  75. // Search the value
  76. char *c;

  78. c = strchr(line, ':');
  79. c++;

  81. dischargeRate = strtoull(c, NULL, 10); // in mW or mA

  83. // Cannot perform conversion
  84. if ((0 == dischargeRate) && (EINVAL == errno))
  85. {
  86. closedir(d);
  87. return result;
  88. }

  90. find++;
  91. }

  93. if (strstr(line, "remaining capacity:") &&
  94. (strstr(line, "mWh") || strstr(line, "mAh")))
  95. {
  96. // Search the value
  97. char *c;

  99. c = strchr(line, ':');
  100. c++;

  102. power_left = strtoull(c, NULL, 10); // in mWh or mAh

  104. // Cannot perform conversion
  105. if ((0 == power_left) && (EINVAL == errno))
  106. {
  107. closedir(d);
  108. return result;
  109. }

  111. find++;
  112. }


  115. }

  117. fclose(file);

  119. // Exit while loop
  120. break;
  121. }
  122. closedir(d);

  124. if (find == 3)
  125. {
  126. result = 0;

  128. if (dischargeRate > 0)
  129. result = (power_left/dischargeRate)*60; // convert to minutes
  130. }

  132. return result;
  133. }


The third method queries whether or not the MID is using an external power source. The information in the file /proc/acpi/ac_adaptor/ACAD/state shows the status of the battery. Below shows the implementation.

  1. int computePowerSource()
  2. {
  3. DIR *d;
  4. struct dirent *de;
  5. char *acadaptor_path = "/proc/acpi/ac_adapter";
  6. char *stateFile = "state";
  7. FILE *file;
  8. int result = -1;
  9. char filename[PATH_LENGTH];

  11. // First, check if the ac_adaptor path exists
  12. if (chdir(acadaptor_path) <>
  13. {
  14. return result;
  15. }

  17. // /proc/acpi/ac_adaptor is found. Now search for available entry
  18. d = opendir(".");
  19. if (!d) {
  20. return result;
  21. }

  23. while ((de = readdir(d))) {
  24. char line[LINE_LENGTH];
  25. // Search for real directory (not ".", ".."
  26. if (!strcmp(de->d_name, "."))
  27. continue;

  29. if (!strcmp(de->d_name, ".."))
  30. continue;

  32. sprintf(filename, "%s/%s/%s", acadaptor_path, de->d_name, stateFile);
  33. file = fopen(filename, "r");
  34. if (!file)
  35. {
  36. closedir(d);
  37. return result;
  38. }

  40. memset(line, 0, LINE_LENGTH);
  41. while (fgets(line, LINE_LENGTH, file) != NULL) {
  42. if (strstr(line, "state:") && strstr(line, "off-line"))
  43. result = 0; // AC (battery)
  44. else if (strstr(line, "state:") && strstr(line, "on-line"))
  45. result = 1; // DC
  46. }

  48. fclose(file);
  49. }

  51. closedir(d);

  53. return result;
  54. }


Putting Things Together


First, the introspection XML in previous section clearly defined the three methods for battery. We can now generate a D-Bus binding header file using the D-Bus binding tool.

  1. % dbus-binding-tool --mode=glib-server -–prefix=MIDPlatformSvc --output=MIDPlatformSvc-dbus-glue.h MIDPlatformSvcInterfaceDefinition.xml


Then, we create a platform service object by following standard steps in [3]. We don't show it here since it is straightforward. In the final step, we just glue the three methods above to the implementation.

Each interface method has three parameters: the called object, the return value, and the error. Inside the interface method we glue the return value to its implementation.

- collapse sourceview plaincopy to clipboardprint?
  1. gboolean getPercentRemaining(MIDPlatformSvc *obj, guint *percentRemaining, GError **error)
  2. {
  3. gboolean rc = FALSE;

  5. rc = computePercentPowerRemaining(percentRemaining);

  7. if (rc)
  8. return TRUE;
  9. else
  10. {
  11. g_set_error(error,
  12. G_FILE_ERROR,
  13. G_FILE_ERROR_NOENT,
  14. "Failed to open file /proc/acpi/battery");
  15. return FALSE;
  16. }
  17. }

  19. gboolean getTimeRemaining(MIDPlatformSvc *obj, gint *timeRemaining, GError **error)
  20. {
  21. *timeRemaining = computeTimeRemaining();

  23. if (*timeRemaining > 0)
  24. {
  25. return TRUE;
  26. }
  27. else if (*timeRemaining == 0)
  28. {
  29. g_set_error(error,
  30. G_FILE_ERROR,
  31. G_FILE_ERROR_NOENT,
  32. "Cannot determine since information is missing!");
  33. return FALSE;
  34. }
  35. else
  36. {
  37. g_set_error(error,
  38. G_FILE_ERROR,
  39. G_FILE_ERROR_NOENT,
  40. "Failed to open file or directory");
  41. return FALSE;
  42. }
  43. }

  45. gboolean isUsingExternalPowerSource(MIDPlatformSvc *obj, gboolean *onExternalSource, GError **error)
  46. {
  47. int t = computePowerSource();

  49. if (t == 0)
  50. {
  51. *onExternalSource = FALSE;
  52. return TRUE;
  53. }
  54. else if (t == 1)
  55. {
  56. *onExternalSource = TRUE;
  57. return TRUE;
  58. }
  59. else
  60. {
  61. g_set_error(error,
  62. G_FILE_ERROR,
  63. G_FILE_ERROR_NOENT,
  64. "Failed to open file or directory");

  66. return FALSE;
  67. }
  68. }


A Test Client


To test the interface power, we write a simple test client using D-Bus as well. The test client invokes the remote methods of object MIDPlatformSvc in order to retrieve battery information on the MID.

  1. #define PLATFORM_SERVICE "org.moblin.Platform"
  2. #define PLATFORM_PATH "/org/moblin/Platform"
  3. #define PLATFORM_POWER_IF "org.moblin.Platform.Power"
  4. #define POWER_SRC_CHANGED_SIGNAL "PowerSourceChanged"

  6. void queryMethod(char* param)
  7. {
  8. DBusGConnection* conn;
  9. GError *error;
  10. DBusGProxy *platformProxy;
  11. DBusError err;

  13. printf("Calling remote method: %s\n", param);

  15. g_type_init();
  16. error = NULL;
  17. conn = dbus_g_bus_get(DBUS_BUS_SESSION, &error);

  19. // Create the proxy Platform
  20. platformProxy = dbus_g_proxy_new_for_name(conn,
  21. PLATFORM_SERVICE, // target for the method call
  22. PLATFORM_PATH, // object to call on
  23. PLATFORM_POWER_IF); // interface to call on

  25. // Now call the metjod "IsUsingExternalPowerSource"
  26. if (param == "GetPercentRemaining")
  27. {
  28. uint result;

  30. if (!dbus_g_proxy_call(platformProxy, param, &error,
  31. G_TYPE_INVALID,
  32. G_TYPE_UINT, &result,
  33. G_TYPE_INVALID))
  34. {
  35. g_printerr("Failed to call remotely: %s\n",
  36. error->message);
  37. g_error_free(error);
  38. }
  39. else
  40. printf ("Remote call successes with returned value: %d%\n", result);
  41. }
  42. else if (param == "GetTimeRemaining")
  43. {
  44. int result;

  46. if (!dbus_g_proxy_call(platformProxy, param, &error,
  47. G_TYPE_INVALID,
  48. G_TYPE_INT, &result,
  49. G_TYPE_INVALID))
  50. {
  51. g_printerr("Failed to call remotely: %s\n",
  52. error->message);
  53. g_error_free(error);
  54. }
  55. else
  56. {
  57. printf ("Remote call successes with returned value: %d minutes\n",result);
  58. }
  59. }
  60. else if (param == "IsUsingExternalPowerSource")
  61. {
  62. gboolean result;

  64. if (!dbus_g_proxy_call(platformProxy, param, &error,
  65. G_TYPE_INVALID,
  66. G_TYPE_BOOLEAN, &result,
  67. G_TYPE_INVALID))
  68. {
  69. g_printerr("Failed to call remotely: %s\n",
  70. error->message);
  71. g_error_free(error);
  72. }
  73. else
  74. printf ("Remote call successes with returned value: %s\n", result? "TRUE" : "FALSE");
  75. }

  77. }

  79. int main(int argc, char** argv)
  80. {
  81. char* methodName[3] = {"GetPercentRemaining",
  82. "GetTimeRemaining",
  83. "IsUsingExternalPowerSource"};

  85. int i;

  87. for (i = 0; i <= 2; i++)
  88. queryMethod(methodName[i]);

  90. return 0;
  91. }


Below is the result when running the test client. 

Calling remote method: IsUsingExternalPowerSource

% ./clientTester

Calling remote method: GetPercentRemaining

Remote call successes with returned value: 96%

Calling remote method: GetTimeRemaining

Remote call successes with returned value: 235 minutes

Calling remote method: IsUsingExternalPowerSource

Remote call successes with returned value: FALSE


Conclusion


Because the MID form factor limits the size of the battery, applications that run on the platform must be aware of power state information in order to make smart decisions. Knowing how much power is remaining, how much time is remaining, and whether or not the system is running on external power can help software make wise use of the MID's resources. D-Bus is a lightweight Remote Procedure Call (RPC) which is suitable for many applications running on desktop. Because D-Bus is simple and relative small, yet powerful, we can adapt this technology for Mobile Internet Device (MID). In this paper, we introduced a platform service for MID using D-Bus technology. We showed how to implement three power-related methods provided by the MIDPlatformSvc. A sample test client is also shown to illustrate how we can use D-Bus to invoke these methods. As D-Bus not only supports methods, it can also support signals; we can also extend this application to include signals. In the feature, this platform service can be extended to include other interfaces such as network, location, CPU utilization...

References


[1] D-Bus, http://www.freedesktop.org/wiki/Software/dbus
[2] D-Bus Tutorial, http://dbus.freedesktop.org/doc/dbus-tutorial.html
[3] http://www.moblin.org/toolkits/basicDevGuides/mobLinux/toolkits_DevGds_mobLinux_createDBUS.php
[4] Mobile and Internet Linux Project, http://moblin.org/



Posted by Unknown at 4:09 AM

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)