doc: pm: Add wakeup information

Add documentation for wakeup sources.

Signed-off-by: Flavio Ceolin <[email protected]>

Author: Flavio Ceolin

doc/reference/power_management/index.rst

@@ -395,6 +395,44 @@ Check Busy Status of All Devices API
 
 Checks if any device is busy. The API returns 0 if no device in the system is busy.
 
+Wakeup capability
+-----------------
+
+Some devices are capable of waking the system up from a sleep state.
+When a device has such capability, applications can enable or disable
+this feature on a device dynamically using
+:c:func:`pm_device_wakeup_enable`.
+
+This property can be set on device declaring the property ``wakeup-source`` in
+the device node in devicetree. For example, this devicetree fragment sets the
+``gpio0`` device as a "wakeup" source:
+
+.. code-block:: devicetree
+
+		gpio0: gpio@40022000 {
+			compatible = "ti,cc13xx-cc26xx-gpio";
+			reg = <0x40022000 0x400>;
+			interrupts = <0 0>;
+			status = "disabled";
+			label = "GPIO_0";
+			gpio-controller;
+			wakeup-source;
+			#gpio-cells = <2>;
+		};
+
+By default, "wakeup" capable devices do not have this functionality enabled
+during the device initialization. Applications can enable this functionality
+later calling :c:func:`pm_device_wakeup_enable`.
+
+.. note::
+
+   This property is **only** used by the system power management to identify
+   devices that should not be suspended.
+   It is responsability of driver or the application to do any additional
+   configuration required by the device to support it.
+
+
+
 Device Runtime Power Management
 *******************************