From 09cead827918caaf5a3ac2f47ebe1c4ba1478197 Mon Sep 17 00:00:00 2001
From: Aleksander Morgado <aleksander@aleksander.es>
Date: Sun, 21 Mar 2021 10:40:34 +0100
Subject: [PATCH] api,sar: improve documentation and add example of SAR mapping
 table

---
 ...rg.freedesktop.ModemManager1.Modem.Sar.xml | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

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" />