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

wifi/1.0/IWifi.hal

@@ -28,8 +28,12 @@ interface IWifi {
   /**
    * 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 @@ interface IWifi {
 
   /**
    * Get the current state of the HAL.
+   *
+   * @return started true if started, false otherwise.
    */
   isStarted() generates (bool started);
 

wifi/1.0/IWifiChip.hal

@@ -125,41 +125,55 @@ interface IWifiChip {
    * 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();
 };

wifi/1.0/IWifiChipEventCallback.hal

@@ -24,7 +24,7 @@ interface IWifiChipEventCallback {
    * 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 @@ interface IWifiChipEventCallback {
    * 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 @@ interface IWifiChipEventCallback {
 
   /**
    * 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);
 };

wifi/1.0/IWifiEventCallback.hal

@@ -28,6 +28,8 @@ interface IWifiEventCallback {
    * 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 @@ interface IWifiEventCallback {
    * 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);
 };