z-stack 2.5.1a code reading note

Code reading note of z-stack 2.5.1a's networking part.

\func - initialization for ZDO and Network Manager.
    ZDApp_Init(taskID++)
    ZDNwkMgr_Init(taskID++)
    
\func - process event for ZDO and Network Manager.
    ZDApp_event_loop
    ZDNwkMgr_event_loop

\typedef devStates_t
    typedef enum
    {
      DEV_HOLD,               // Initialized - not started automatically
                              // jt - refer to `HOLD_AUTO_START`
      DEV_INIT,               // Initialized - not connected to anything
      DEV_NWK_DISC,           // Discovering PAN's to join
      DEV_NWK_JOINING,        // Joining a PAN
      DEV_NWK_REJOIN,         // ReJoining a PAN, only for end devices
      DEV_END_DEVICE_UNAUTH,  // Joined but not yet authenticated by trust center
      DEV_END_DEVICE,         // Started as device after authentication
      DEV_ROUTER,             // Device joined, authenticated and is a router
      DEV_COORD_STARTING,     // Starting as Zigbee Coordinator
      DEV_ZB_COORD,           // Started as Zigbee Coordinator
      DEV_NWK_ORPHAN          // Device has lost information about its parent..
    } devStates_t;
    
\typedef devStartModes_t
    typedef enum
    {
      MODE_JOIN,        // jt - assume joining
      MODE_RESUME,      // jt - set to make device do an Orphan scan.
      MODE_HARD,
      MODE_REJOIN
    } devStartModes_t;
    
\prefix AIB_
    Application Support (APS) Sub-layer Information Base
    
\func ZDApp_Init
    ZDOInitDevice(0 /* ZDO_INIT_HOLD_NWK_START */);
    ZDApp_InitZdoCBFunc(); // init zdoCBFunc to nullptr's.
        typedef void* (*pfnZdoCb)(void *param);
        pfnZdoCb zdoCBFunc[MAX_ZDO_CB_FUNC];
        enum
        {
          ZDO_SRC_RTG_IND_CBID,
          ZDO_CONCENTRATOR_IND_CBID,
          ZDO_NWK_DISCOVERY_CNF_CBID,
          ZDO_BEACON_NOTIFY_IND_CBID,
          ZDO_JOIN_CNF_CBID,
          ZDO_LEAVE_CNF_CBID,
          ZDO_LEAVE_IND_CBID,
          MAX_ZDO_CB_FUNC               // Must be at the bottom of the list
        };
    ZDApp_RegisterCBs();
        ZDO_RegisterForZDOMsg(ZDAppTaskID, Bind_rsp); // task_id, cluster_id
        
\func ZDNwkMgr_Init - only for `ZG_BUILD_RTR_TYPE`, not for `ZG_BUILD_ENDDEVICE_TYPE`.
    /**
     * jtuki - We don't use Network Manager to handle channel interference and 
     *    pan_id conflict, so we wanna set all these callback_fn to nullptr.
     */
    
\file ZDProfile.h
    This file contains the interface to the Zigbee Device Object.
    
\func ZDO_RegisterForZDOMsg
    // linked list of ZDO's message callbacks.
    ZDO_MsgCB_t *zdoMsgCBs = (ZDO_MsgCB_t *)NULL;
    
\func ZDOInitDevice
    /**
     * Startup options - \func zgWriteStartupOptions(action, bitOptions)
     * NV item - `ZCD_NV_STARTUP_OPTION`, bitOptions `ZCD_STARTOPT_DEFAULT_NETWORK_STATE` etc.
     *
     * The most two important parameter of startup option:
     *      \global devStartMode
     *      \global devState
     *
     * @return
     *      ZDO_INITDEV_RESTORED_NETWORK_STATE
     *      ZDO_INITDEV_NEW_NETWORK_STATE
     *      ZDO_INITDEV_LEAVE_NOT_STARTED
     */
    // Refer to comments of the function!
    ZDApp_RestoreNetworkState(void)
        devStartMode = MODE_RESUME; // for end-device, do orphan scan.
    ZDAppDetermineDeviceType()
        /**
         * vds: jtuki - for end devices, if ExtendedPANID is considered valid, the
         *    `devStartMode` will be set to MODE_REJOIN, instead of MODE_JOIN.
         */
    
\func ZDApp_event_loop
    \message
        ZDApp_ProcessOSALMsg
    \event ZDO_NETWORK_INIT
        \sa \func ZDApp_NetworkInit (delay)
        ZDO_StartDevice(
            (uint8)ZDO_Config_Node_Descriptor.LogicalType, devStartMode,
            DEFAULT_BEACON_ORDER, DEFAULT_SUPERFRAME_ORDER
            );
    \event ZDO_STATE_CHANGE_EVT
        ZDO_UpdateNwkStatus(devState);
        #mark#
    \event ZDO_NWK_UPDATE_NV
        /**
         * vds: jtuki - special note here.
         *    Refer to \macro NV_TURN_OFF_RADIO. This macro is only used within the
         *    function below. But the question is, when and why to use NV_TURN_OFF_RADIO?
         *    
         *    I cannot find any document or reference relates to the question.
         *    Does receiving over-the-air packets conflicts with updating NV items?
         */
        ZDApp_SaveNetworkStateEvt();
    \event ZDO_DEVICE_RESET
        // force a "new" join.
        zgWriteStartupOptions(ZG_STARTUP_SET, ZCD_STARTOPT_DEFAULT_NETWORK_STATE);
        SystemResetSoft();

\func ZDApp_ProcessOSALMsg
    // switch(msgPtr->event):
    \event ZDO_NWK_JOIN_IND
        ZDApp_ProcessNetworkJoin();
    \event ZDO_NWK_JOIN_REQ
        /**
         * vds: jtuki - only ZDO_SyncIndicationCB() send \msg ZDO_NWK_JOIN_REQ here.
         *    As to rejoin, use the extended-PANID (previous AP's MAC address).
         */
        ZDApp_NetworkInit(0);
    \event ZDO_NWK_DISC_CNF
        (pChosenNwk = ZDApp_NwkDescListProcessing()) != NULL
        
    #mark#

\func ZDApp_NetworkInit (delay)
    osal_start_timerEx(ZDAppTaskID, ZDO_NETWORK_INIT, delay);
 
\func ZDApp_ProcessNetworkJoin
    \sa \func ZDApp_ProcessOSALMsg() with \event ZDO_NWK_JOIN_IND
    #mark#
            
\func ZDApp_NwkDescListProcessing
    #mark#

\func ZDO_StartDevice
    /**
     * vds: jtuki - We don't use \macro MANAGED_SCAN, and only have one static channel.
     *    Previously, we have encountered a problem:
     *      http://e2e.ti.com/support/wireless_connectivity/f/158/p/333653/1163938.aspx
     *    Here might be the solution for the problem.
     *      Use "BEACON_ORDER_120_MSEC" instead of "STARTING_SCAN_DURATION" (480ms).
     */
    ret = NLME_NetworkDiscoveryRequest(zgDefaultChannelList, BEACON_ORDER_120_MSEC);
    
\func ZDNwkMgr_event_loop
    #mark#
    
\func ZDO_NetworkDiscoveryConfirmCB
    #mark#
    
\func ZDO_NetworkFormationConfirmCB
    #mark#
    
\func ZDO_beaconNotifyIndCB
    #mark#
    
\func ZDO_StartRouterConfirmCB
    #mark#
    
\func ZDO_JoinConfirmCB
    \sa \func ZDApp_ProcessOSALMsg with \event ZDO_NWK_JOIN_IND
    /**
     * @brief    This function allows the next hight layer to be notified
     *           of the results of its request to join itself or another
     *           device to a network.
     *          
     * @param    Status - Result of NLME_JoinRequest()
     */
    ZDApp_SendMsg(ZDAppTaskID, ZDO_NWK_JOIN_IND, sizeof(osal_event_hdr_t), (byte*)NULL);
    #mark#
    
\func ZDO_AddrChangeIndicationCB
    #mark#
    
\func ZDO_JoinIndicationCB
    #mark#
    
\func ZDO_ConcentratorIndicationCB
    #mark#
    
\func ZDO_SyncIndicationCB
    /**
     * When sensorNode losts contact with parent node, sensorNode will have
     * an indication of "lost contact", and \func ZDO_SyncIndicationCB will
     * send ZDO_STATE_CHANGE (with info "nwk_orphan") event.
     */
    
\func ZDO_ManytoOneFailureIndicationCB
    #mark#
    
\func ZDO_LeaveCnf (NLME_LeaveCnf_t* cnf)
    typedef struct
    {
      uint16 dstAddr;
      uint8  extAddr[Z_EXTADDR_LEN];
      uint8  removeChildren;
      uint8  rejoin;
      uint8  status;
    } NLME_LeaveCnf_t;
    #mark#
    
\func ZDO_LeaveInd (NLME_LeaveInd_t* ind)
    typedef struct
    {
      uint16 srcAddr;
      uint8  extAddr[Z_EXTADDR_LEN];
      uint8  request;
      uint8  removeChildren;
      uint8  rejoin;
    } NLME_LeaveInd_t;
    #mark#
    
\func ZDApp_CoordStartPANIDConflictCB
    return (panid + 1);
    
\func ZDApp_NVUpdate()
    #mark#
    \sa \macro ZDO_NV_SAVE_RFDs
    
    // Delay time before updating NWK NV data to force fewer writes during high activity.
    \sa \macro ZDAPP_UPDATE_NWK_NV_TIME

\macro ZDO_NV_SAVE_RFDs
    \sa ZDO_JoinIndicationCB()
        #if ZDO_NV_SAVE_RFDs
          (void) CapabilityFlags;
        #else  // if !ZDO_NV_SAVE_RFDs
          if (CapabilityFlags & CAPINFO_DEVICETYPE_FFD)
        #endif
          {
            ZDApp_NVUpdate(); // Notify to save info into NV.
          }

\func ZDO_ProcessDeviceAnnce
    \brief This function processes a device annouce message.
    /**
     * vds: jtuki - many operations handle the association list etc.
     *  Refer to this function if you wanna modify assoc_list/nwk_addr_mgr etc.
     */

\func osal_pwrmgr_init
    typedef struct
    {
      uint16 pwrmgr_task_state; // a bit-vector value.
      uint16 pwrmgr_next_timeout;
      uint16 accumulated_sleep_time;
      uint8  pwrmgr_device; // PWRMGR_ALWAYS_ON or PWRMGR_BATTERY
    } pwrmgr_attribute_t;
    pwrmgr_attribute_t pwrmgr_attribut;e