From de48acf9fbc86ed826337dd70c7dc2408f1c2cd6 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Thu, 2 Mar 2017 21:47:08 -0800 Subject: [PATCH] Update comments: Source Match feature and poll period selection (#1400) This commit adds/updates comments. It contains no code/logic change. - Adds comments to describe expected behavior and use of source address match feature and the related radio platform functions. - Updates comments to describe the selection of poll period and the `SetAssignPollPeriod()`. --- include/openthread/platform/radio.h | 31 +++++++++++++++++++---------- src/core/thread/mesh_forwarder.hpp | 21 +++++++++++++++---- 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index c5dab5ade..65df7f656 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -254,15 +254,26 @@ ThreadError otPlatRadioSleep(otInstance *aInstance); ThreadError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel); /** - * Enable/Disable source match for AutoPend. + * Enable/Disable source address match feature. + * + * The source address match feature controls how the radio layer decides the "frame pending" bit for acks sent in + * response to data request commands from children. + * + * If disabled, the radio layer must set the "frame pending" on all acks to data request commands. + * + * If enabled, the radio layer uses the source address match table to determine whether to set or clear the "frame + * pending" bit in an ack to a data request command. + * + * The source address match table provides the list of children for which there is a pending frame. Either a short + * address or an extended/long address can be added to the source address match table. * * @param[in] aInstance The OpenThread instance structure. - * @param[in] aEnable Enable/disable source match for automatical pending. + * @param[in] aEnable Enable/disable source address match feature. */ void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable); /** - * Adding short address to the source match table. + * Add a short address to the source address match table. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aShortAddress The short address to be added. @@ -273,7 +284,7 @@ void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable); ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress); /** - * Adding extended address to the source match table. + * Add an extended address to the source address match table. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aExtAddress The extended address to be added. @@ -284,29 +295,29 @@ ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16 ThreadError otPlatRadioAddSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress); /** - * Removing short address to the source match table. + * Remove a short address from the source address match table. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aShortAddress The short address to be removed. * * @retval ::kThreadError_None Successfully removed short address from the source match table. - * @retval ::kThreadError_NoAddress The short address is not in source match table. + * @retval ::kThreadError_NoAddress The short address is not in source address match table. */ ThreadError otPlatRadioClearSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress); /** - * Removing extended address to the source match table of the radio. + * Remove an extended address from the source address match table. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aExtAddress The extended address to be removed. * * @retval ::kThreadError_None Successfully removed the extended address from the source match table. - * @retval ::kThreadError_NoAddress The extended address is not in source match table. + * @retval ::kThreadError_NoAddress The extended address is not in source address match table. */ ThreadError otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress); /** - * Removing all the short addresses from the source match table. + * Clear all short addresses from the source address match table. * * @param[in] aInstance The OpenThread instance structure. * @@ -314,7 +325,7 @@ ThreadError otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const uint8_ void otPlatRadioClearSrcMatchShortEntries(otInstance *aInstance); /** - * Removing all the extended addresses from the source match table. + * Clear all the extended/long addresses from source address match table. * * @param[in] aInstance The OpenThread instance structure. * diff --git a/src/core/thread/mesh_forwarder.hpp b/src/core/thread/mesh_forwarder.hpp index 9fcf9d317..75d353ea0 100644 --- a/src/core/thread/mesh_forwarder.hpp +++ b/src/core/thread/mesh_forwarder.hpp @@ -139,15 +139,22 @@ public: void SetRxOnWhenIdle(bool aRxOnWhenIdle); /** - * This method sets customized Data Poll period. Only for certification test + * This method sets a user-specified Data Poll period. * - * @param[in] aPeriod The Data Poll period in milliseconds. + * If the value is set to zero, then the poll interval is managed by the OpenThread stack. + * If the user has provided a non-zero poll period, the user value specifies the maximum period between data + * request transmissions. Note that OpenThread may send data request transmissions more frequently when expecting + * a control-message from a parent. + * + * Initial/Default value for "assign poll period" is zero. + * + * @param[in] aPeriod The Data Poll period in milliseconds, or zero to mean no user-specified poll period. * */ void SetAssignPollPeriod(uint32_t aPeriod); /** - * This method gets the customized Data Poll period. Only for certification test + * This method gets the current user-specified Data Poll period. * * @returns The Data Poll period in milliseconds. * @@ -155,7 +162,13 @@ public: uint32_t GetAssignPollPeriod(void); /** - * This method sets the Data Poll period. + * + * This method sets the maximum period between data request command transmissions. Note that OpenThread may send + * data request transmissions more frequently when expecting a control-message from a parent. + * + * If the user has provided a non-zero assign poll period (@sa SetAssignPollPeriod), the user value specifies the + * maximum period between data request command transmissions and is used in place of @p aPeriod. + * * * @param[in] aPeriod The Data Poll period in milliseconds. *