adl_memRelease() badly documented; undocumented side-effect


The Downloader sample Library (used in the Application Download sample) seems to assume that adl_memRelease() will clear the pointer supplied in its parameter.

The ADL User Guide makes no mention of clearing the pointer. :angry:

/* Download main function */
void dwl_DownProc ( u16 Length, u8 * Data )
    static u8 * CurrentBlock = NULL;

            /* Transmission : new or existing block */
            if ( !CurrentBlock )
                /* Set type XMODEM or 1K XMODEM */
                CurrentType = Data[ 0 ];
                /* New block */
                CurrentBlock = adl_memGet( (u16)(BLOCK_SIZE(CurrentType)) );
                TRACE (( dwl_TraceLevel, "First datas" ));
                TRACE (( 10, "Start Block %d", Data[1] ));

                /* Release Block */
                adl_memRelease ( CurrentBlock );
                CurrentPos = 0;

Note that the CurrentBlock is not explicitly cleared when the block is released, but the code does rely upon CurrentBlock being NULL to decide when to allocate a new block!

This doesn’t seem to make sense, since CurrentBlock appears to be passed by value! :open_mouth:

In fact, the prototype shown in the ADL User Guide is wrong:

bool adl_memRelease( void ptr )

adl_memRelease is not actually a function at all - it’s a macro, defined in adl_memory.h:

// Memory release macro
#define adl_memRelease(_p_) _adl_memRelease( ( void ** ) &_p_ )

So now it becomes clear how the pointer can be cleared!

This kind of stuff really should be clearly documented in the manual! :angry: