From 390500639f1aff293fdad73a4414727195e3a444 Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Wed, 20 Sep 2023 14:43:18 -0700 Subject: [PATCH] [docs] add Doxygen tags for CLI commands (`macfilter` - `macfilter addr`) (#9424) --- include/openthread/instance.h | 2 +- include/openthread/link.h | 28 ++++---- src/cli/cli_mac_filter.cpp | 128 +++++++++++++++++++++++++++++++++- 3 files changed, 141 insertions(+), 17 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index f97cc68cf7c..424cf09a785 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (358) +#define OPENTHREAD_API_VERSION (359) /** * @addtogroup api-instance diff --git a/include/openthread/link.h b/include/openthread/link.h index 5c920db9e5b..76b5d39eb68 100644 --- a/include/openthread/link.h +++ b/include/openthread/link.h @@ -714,7 +714,7 @@ void otLinkSetMaxFrameRetriesIndirect(otInstance *aInstance, uint8_t aMaxFrameRe /** * Gets the address mode of MAC filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -726,7 +726,7 @@ otMacFilterAddressMode otLinkFilterGetAddressMode(otInstance *aInstance); /** * Sets the address mode of MAC filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aMode The address mode to set. @@ -737,7 +737,7 @@ void otLinkFilterSetAddressMode(otInstance *aInstance, otMacFilterAddressMode aM /** * Adds an Extended Address to MAC filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the Extended Address (MUST NOT be NULL). @@ -751,7 +751,7 @@ otError otLinkFilterAddAddress(otInstance *aInstance, const otExtAddress *aExtAd /** * Removes an Extended Address from MAC filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * No action is performed if there is no existing entry in Filter matching the given Extended Address. * @@ -764,7 +764,7 @@ void otLinkFilterRemoveAddress(otInstance *aInstance, const otExtAddress *aExtAd /** * Clears all the Extended Addresses from MAC filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -774,7 +774,7 @@ void otLinkFilterClearAddresses(otInstance *aInstance); /** * Gets an in-use address filter entry. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the MAC filter iterator context. To get the first in-use address filter @@ -791,7 +791,7 @@ otError otLinkFilterGetNextAddress(otInstance *aInstance, otMacFilterIterator *a * Adds a fixed received signal strength (in dBm) entry for the messages from a given Extended Address in * MAC Filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in] aExtAddress A pointer to the IEEE 802.15.4 Extended Address. MUST NOT be NULL. @@ -806,7 +806,7 @@ otError otLinkFilterAddRssIn(otInstance *aInstance, const otExtAddress *aExtAddr /** * Removes a MAC Filter entry for fixed received signal strength setting for a given Extended Address. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * No action is performed if there is no existing entry in Filter matching the given Extended Address. * @@ -819,7 +819,7 @@ void otLinkFilterRemoveRssIn(otInstance *aInstance, const otExtAddress *aExtAddr /** * Sets the default received signal strength (in dBm) on MAC Filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry * in the Filter list (added using `otLinkFilterAddRssIn()`). @@ -833,7 +833,7 @@ void otLinkFilterSetDefaultRssIn(otInstance *aInstance, int8_t aRss); /** * Clears any previously set default received signal strength (in dBm) on MAC Filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -843,7 +843,7 @@ void otLinkFilterClearDefaultRssIn(otInstance *aInstance); /** * Clears all the received signal strength entries (including default RSS-in) on MAC Filter. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @@ -853,7 +853,7 @@ void otLinkFilterClearAllRssIn(otInstance *aInstance); /** * Gets an in-use RssIn filter entry. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @param[in] aInstance A pointer to an OpenThread instance. * @param[in,out] aIterator A pointer to the MAC filter iterator context. MUST NOT be NULL. @@ -871,7 +871,7 @@ otError otLinkFilterGetNextRssIn(otInstance *aInstance, otMacFilterIterator *aIt /** * Enables/disables IEEE 802.15.4 radio filter mode. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * The radio filter is mainly intended for testing. It can be used to temporarily block all tx/rx on the 802.15.4 radio. * When radio filter is enabled, radio is put to sleep instead of receive (to ensure device does not receive any frame @@ -887,7 +887,7 @@ void otLinkSetRadioFilterEnabled(otInstance *aInstance, bool aFilterEnabled); /** * Indicates whether the IEEE 802.15.4 radio filter is enabled or not. * - * Is available when OPENTHREAD_CONFIG_MAC_FILTER_ENABLE configuration is enabled. + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. * * @retval TRUE If the radio filter is enabled. * @retval FALSE If the radio filter is disabled. diff --git a/src/cli/cli_mac_filter.cpp b/src/cli/cli_mac_filter.cpp index 7201c0423bd..95cf1c2273d 100644 --- a/src/cli/cli_mac_filter.cpp +++ b/src/cli/cli_mac_filter.cpp @@ -137,10 +137,49 @@ template <> otError MacFilter::Process(Arg aArgs[]) otError error = OT_ERROR_NONE; otExtAddress extAddr; + /** + * @cli macfilter addr + * @code + * macfilter addr + * Allowlist + * 0f6127e33af6b403 : rss -95 (lqi 1) + * 0f6127e33af6b402 + * Done + * @endcode + * @par + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. + * @par + * Provides the following information: + * - Current mode of the MAC filter list: Either `AllowList`, `DenyList,` or `Disabled` + * - A list of all the extended addresses in the filter. The received signal strength (rss) and + * link quality indicator (lqi) are listed next to the address if these values have been set to be + * different from the default values. + * @sa otLinkFilterGetAddressMode + */ if (aArgs[0].IsEmpty()) { OutputFilter(kAddressFilter); } + /** + * @cli macfilter addr add + * @code + * macfilter addr add 0f6127e33af6b403 -95 + * Done + * @endcode + * @code + * macfilter addr add 0f6127e33af6b402 + * Done + * @endcode + * @cparam macfilter addr add @ca{extaddr} [@ca{rss}] + * @par + * Is available only when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. + * @par + * Adds an IEEE 802.15.4 Extended Address to the MAC filter list. + * If you specify the optional `rss` argument, this fixes the received signal strength for messages from the + * address. If you do not use the `rss` option, the address will use whatever default value you have set. + * If you have not set a default, the signal strength will be the over-air signal. + * @sa otLinkFilterAddAddress + */ else if (aArgs[0] == "add") { SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8)); @@ -156,11 +195,39 @@ template <> otError MacFilter::Process(Arg aArgs[]) SuccessOrExit(error = otLinkFilterAddRssIn(GetInstancePtr(), &extAddr, rss)); } } + /** + * @cli macfilter addr remove + * @code + * macfilter addr remove 0f6127e33af6b402 + * Done + * @endcode + * @cparam macfilter addr remove @ca{extaddr} + * @par + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. + * @par + * This command removes the specified extended address from the MAC filter list. + * @note No action is performed if the specified extended address does not match an entry in the MAC filter list. + * @sa otLinkFilterRemoveAddress + */ else if (aArgs[0] == "remove") { SuccessOrExit(error = aArgs[1].ParseAsHexString(extAddr.m8)); otLinkFilterRemoveAddress(GetInstancePtr(), &extAddr); } + /** + * @cli macfilter addr clear + * @code + * macfilter addr clear + * Done + * @endcode + * @par + * Is available when `OPENTHREAD_CONFIG_MAC_FILTER_ENABLE` configuration is enabled. + * @par + * This command clears all the extended addresses from the MAC filter list. + * @note This command does not affect entries in the `RssIn` list. That list contains extended addresses where the + * `rss` has been set to a fixed value that differs from the default. + * @sa otLinkFilterClearAddresses + */ else if (aArgs[0] == "clear") { otLinkFilterClearAddresses(GetInstancePtr()); @@ -168,9 +235,40 @@ template <> otError MacFilter::Process(Arg aArgs[]) else { static const char *const kModeCommands[] = { - "disable", // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED + /** + * @cli macfilter addr disable + * @code + * macfilter addr disable + * Done + * @endcode + * @par + * Disables MAC filter modes. + */ + "disable", // (0) OT_MAC_FILTER_ADDRESS_MODE_DISABLED + /** + * @cli macfilter addr allowlist + * @code + * macfilter addr allowlist + * Done + * @endcode + * @par + * Enables the `allowlist` MAC filter mode, which means that only the MAC addresses in the MAC filter list + * will be allowed access. + * @sa otLinkFilterSetAddressMode + */ "allowlist", // (1) OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST - "denylist", // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST + /** + * @cli macfilter addr denylist + * @code + * macfilter addr denylist + * Done + * @endcode + * @par + * Enables the `denylist` MAC filter mode, which means that all MAC addresses in the MAC filter list + * will be denied access. + * @sa otLinkFilterSetAddressMode + */ + "denylist", // (2) OT_MAC_FILTER_ADDRESS_MODE_DENYLIST }; for (size_t index = 0; index < OT_ARRAY_LENGTH(kModeCommands); index++) @@ -276,6 +374,32 @@ otError MacFilter::Process(Arg aArgs[]) otError error = OT_ERROR_INVALID_COMMAND; const Command *command; + /** + * @cli macfilter + * @code + * macfilter + * Address Mode: Allowlist + * 0f6127e33af6b403 : rss -95 (lqi 1) + * 0f6127e33af6b402 + * RssIn List: + * 0f6127e33af6b403 : rss -95 (lqi 1) + * Default rss: -50 (lqi 3) + * Done + * @endcode + * @par + * Provides the following information: + * - `Address Mode`: Current mode of the MAC filter: Either `AllowList`, `DenyList,` or `Disabled` + * - A list of all the extended addresses in the MAC filter list. The received signal strength (rss) and + * link quality indicator (lqi) are listed next to the address if these values have been set to be + * different from the default values. + * - A separate list (`RssIn List`) that shows all the extended addresses where the `rss` has been set to + * be different from the default value. + * - `Default rss`: Shows the default values, if applicable, for the `rss` and `lqi` settings. + * @note An extended address can be in the `RssIn` list without being in the MAC filter list. + * @sa otLinkFilterSetAddressMode + * @sa otLinkFilterGetNextAddress + * @sa otLinkFilterGetNextRssIn + */ if (aArgs[0].IsEmpty()) { OutputFilter(kAddressFilter | kRssFilter);