api,sar: improve documentation and add example of SAR mapping table

1 files changed, 29 insertions, 1 deletions

diff --git a/introspection/org.freedesktop.ModemManager1.Modem.Sar.xml b/introspection/org.freedesktop.ModemManager1.Modem.Sar.xml
index 1c96617a..5acffc5f 100644
--- a/introspection/org.freedesktop.ModemManager1.Modem.Sar.xml
+++ b/introspection/org.freedesktop.ModemManager1.Modem.Sar.xml
@@ -12,7 +12,33 @@
       org.freedesktop.ModemManager1.Modem.Sar:
       @short_description: The ModemManager dynamic SAR interface.
 
-      The SAR interface defines operations and properties for dynamic SAR.
+      The SAR interface defines operations and properties for dynamic SAR, so
+      that user applications can control the output power level dynamically.
+
+      Using the SAR interface is not trivial, and it requires prior knowledge of
+      the internal SAR mapping table configured in each device.
+
+      The SAR mapping table is defined by the manufacturer of the device, and is
+      usually setup to match a specific hardware setup (e.g. a specific laptop or
+      hardware configuration). This table may provide different power levels for
+      different frequency bands and/or antennas.
+
+      An example SAR mapping table, where all bands and antennas share the same
+      level, could look like this:
+      <table>
+        <tr><td>Power Level</td><td>LTE B3</td>   <td>LTE B7</td>   <td>LTE B20</td></tr>
+        <tr><td>0</td>          <td>26.0 dBm</td> <td>26.5 dBm</td> <td>27.0 dBm</td></tr>
+        <tr><td>1</td>          <td>26.5 dBm</td> <td>27.0 dBm</td> <td>27.5 dBm</td></tr>
+        <tr><td>2</td>          <td>27.0 dBm</td> <td>27.5 dBm</td> <td>28.0 dBm</td></tr>
+        <tr><td>3</td>          <td>27.5 dBm</td> <td>28.0 dBm</td> <td>28.5 dBm</td></tr>
+        <tr><td>4</td>          <td>28.0 dBm</td> <td>28.5 dBm</td> <td>28.5 dBm</td></tr>
+        <tr><td>5</td>          <td>28.5 dBm</td> <td>28.5 dBm</td> <td>28.5 dBm</td></tr>
+      </table>
+
+      In this example, the SAR mapping table has 6 different levels (0 to 5),
+      and it's applied exclusively for LTE bands B3, B7 and B20 in all available
+      antennas. None of this information is exposed to the user in the SAR
+      interface, not even the amount of levels available.
   -->
   <interface name="org.freedesktop.ModemManager1.Modem.Sar">
 
@@ -59,6 +85,8 @@
 
         Current index of the SAR power level mapping table that is being used
         for setting the output power of all antennas on the system.
+
+        This value is only applicable when dynamic SAR is enabled.
     -->
     <property name="PowerLevel" type="u" access="read" />