wifi(interface): Add/Correct docstring params
Changes in the CL:
1. Add missing docstring params in the HIDL interface.
2. Reword some method docs. Occurences of "will" is replaced
by "must" (based on comments received on supplicant HIDL interface:
go/aog/275115).
3. Add onFailure callbacks for all the methods and added docstrings for
them.
Bug: 31352200
Test: mmma -j32 hardware/interfaces/wifi/1.0
Change-Id: Ib7152625851023d6244f742bb77a8fdc0829e00d
diff --git a/wifi/1.0/IWifi.hal b/wifi/1.0/IWifi.hal
index 1feeb2a..d1311f5 100644
--- a/wifi/1.0/IWifi.hal
+++ b/wifi/1.0/IWifi.hal
@@ -28,8 +28,12 @@
/**
* Requests notifications of significant events for the HAL. Multiple calls to
* this must register multiple callbacks each of which must receive all
- * events. IWifiEventCallback registration must be independent of the state
- * of the rest of the HAL and must persist though stops/starts.
+ * events. |IWifiEventCallback| object registration must be independent of the
+ * state of the rest of the HAL and must persist though stops/starts. These
+ * objects must be deleted when the corresponding client process is dead.
+ *
+ * @param callback An instance of the |IWifiEventCallback| HIDL interface
+ * object.
*/
@entry
@callflow(next={"*"})
@@ -37,6 +41,8 @@
/**
* Get the current state of the HAL.
+ *
+ * @return started true if started, false otherwise.
*/
isStarted() generates (bool started);
diff --git a/wifi/1.0/IWifiChip.hal b/wifi/1.0/IWifiChip.hal
index f5fe7a9..3e229e2 100644
--- a/wifi/1.0/IWifiChip.hal
+++ b/wifi/1.0/IWifiChip.hal
@@ -125,41 +125,55 @@
* Requests notifications of significant events on this chip. Multiple calls
* to this will register multiple callbacks each of which will receive all
* events.
+ *
+ * @param callback An instance of the |IWifiChipEventCallback| HIDL interface
+ * object.
*/
oneway registerEventCallback(IWifiChipEventCallback callback);
/**
* Get the set of operation modes that the chip supports.
+ *
+ * @return modes List of modes supported by the device.
*/
getAvailableModes() generates (vec<ChipMode> modes);
/**
- * Reconfigure the Chip. Will trigger onChipReconfigured.
+ * Reconfigure the Chip.
+ * Must trigger |IWifiChipEventCallback.onChipReconfigured| on sucess,
+ * or |IWifiChipEventCallback.onChipReconfigureFailure| on failure.
*
* @param modeId The mode that the chip should switch to, corresponding to the
- * id property of the target ChipMode.
+ * id property of the target ChipMode.
*/
oneway configureChip(ChipModeId modeId);
/**
* Get the current mode that the chip is in.
+ *
+ * @return modeId The mode that the chip is currently configured to,
+ * corresponding to the id property of the target ChipMode.
*/
getMode() generates (ChipModeId modeId);
/**
- * Request information about the chip. Will trigger onChipDebugInfoAvailable.
+ * Request information about the chip.
+ * Must trigger |IWifiChipEventCallback.onChipDebugInfoAvailable| on sucess,
+ * or |IWifiChipEventCallback.onChipDebugInfoFailure| on failure.
*/
oneway requestChipDebugInfo();
/**
- * Request vendor debug info from the driver. Will trigger
- * onDriverDebugDumpAvailable.
+ * Request vendor debug info from the driver.
+ * Must trigger |IWifiChipEventCallback.onDriverDebugDumpAvailable| on success,
+ * or |IWifiChipEventCallback.onDriverDebugDumpFailure| on failure.
*/
oneway requestDriverDebugDump();
/**
- * Request vendor debug info from the firmware. Will trigger
- * onFirmwareDebugDumpAvailable.
+ * Request vendor debug info from the firmware.
+ * Must trigger |IWifiChipEventCallback.onFirmwareDebugDumpAvailable| on
+ * success, or |IWifiChipEventCallback.onFirmwareDebugDumpFailure| on failure.
*/
oneway requestFirmwareDebugDump();
};
diff --git a/wifi/1.0/IWifiChipEventCallback.hal b/wifi/1.0/IWifiChipEventCallback.hal
index 79f6d2a..2161c5d 100644
--- a/wifi/1.0/IWifiChipEventCallback.hal
+++ b/wifi/1.0/IWifiChipEventCallback.hal
@@ -24,7 +24,7 @@
* considered invalid.
*
* @param modeId The mode that the chip switched to, corresponding to the id
- * property of the target ChipMode.
+ * property of the target ChipMode.
*/
oneway onChipReconfigured(ChipModeId modeId);
@@ -34,7 +34,8 @@
* assumed to be invalid.
*
* @param modeId The mode that the chip failed switched to, corresponding to
- * the id property of the target ChipMode.
+ * the id property of the target ChipMode.
+ * @param reason Failure reason code.
*/
oneway onChipReconfigureFailure(ChipModeId modeId, FailureReason reason);
@@ -51,18 +52,45 @@
/**
* Callback with debug information about this chip
+ *
+ * @param info Instance of |ChipDebugInfo|.
*/
oneway onChipDebugInfoAvailable(ChipDebugInfo info);
/**
- * Callback with a vendor specific debug blob from the driver.
- * This blob will be dumped as part of the bug report.
+ * Callback to be invoked on failure to fetch debug info about this chip.
+ *
+ * @param reason Failure reason code.
*/
- oneway onDriverDebugDumpAvailable(vec<uint8_t> blob);
+ oneway onChipDebugInfoFailure(FailureReason reason);
/**
* Callback with a vendor specific debug blob from the driver.
* This blob will be dumped as part of the bug report.
+ *
+ * @param blob Vector of bytes retrieved from the driver.
+ */
+ oneway onDriverDebugDumpAvailable(vec<uint8_t> blob);
+
+ /**
+ * Callback to be invoked on failure to fetch debug blob from driver.
+ *
+ * @param reason Failure reason code.
+ */
+ oneway onDriverDebugDumpFailure(FailureReason reason);
+
+ /**
+ * Callback with a vendor specific debug blob from the driver.
+ * This blob will be dumped as part of the bug report.
+ *
+ * @param blob Vector of bytes retrieved from the driver.
*/
oneway onFirmwareDebugDumpAvailable(vec<uint8_t> blob);
+
+ /**
+ * Callback to be invoked on failure to fetch debug blob from driver.
+ *
+ * @param reason Failure reason code.
+ */
+ oneway onFirmwareDebugDumpFailure(FailureReason reason);
};
diff --git a/wifi/1.0/IWifiEventCallback.hal b/wifi/1.0/IWifiEventCallback.hal
index 84025ce..33accff 100644
--- a/wifi/1.0/IWifiEventCallback.hal
+++ b/wifi/1.0/IWifiEventCallback.hal
@@ -28,6 +28,8 @@
* failed. After this callback the HAL will be considered stopped. Another
* call to start will attempt to reinitialize the HAL; however, there is a
* chance it may fail again.
+ *
+ * @param reason Failure reason code.
*/
oneway onStartFailure(FailureReason reason);
@@ -43,6 +45,8 @@
* Calling start again must restart Wi-Fi as if stop then start was called
* (full state reset). When this event is received all IWifiChip objects
* retrieved after the last call to start will be considered invalid.
+ *
+ * @param reason Failure reason code.
*/
oneway onFailure(FailureReason reason);
};