Common.h File Reference

Common Support Functions: Definitions and Prototypes More...

Data Structures
struct	PACKET
struct	T_ComDevice

Macros
#define	COMMON_CODE_SECTION   ".commontext"
#define	PRAGMA(x)   _Pragma(#x)
#define	LOOP_COUNT_INFO(min, multiple)   PRAGMA(MUST_ITERATE(min,,multiple))
#define	VAR_IN_SECTION(var, section)   PRAGMA(DATA_SECTION(var, #section))
#define	PTR_IS_ALIGNED(ptr, pow2)   _nassert(((uint32_t) (ptr) & (pow2)-1) == 0);
#define	CSPRAGMA(f, s)   PRAGMA(CODE_SECTION(f, s))
#define	_CPP_extern_open_
#define	_CPP_extern_close_
#define	NULL   ((void *)UINT32_C(0))
#define	_CODE_ACCESS   far
#define	_DATA_ACCESS   far
#define	UNREFERENCED_PARAMETER(P)    ((P)=(P)) \
#define	UNUSED_PARAMETER(P)    ((void)(P)) \
#define	BUILD_YEAR
#define	BUILD_DAY   ((__DATE__ [4] == ' ' ? 0 : __DATE__ [4] - '0') * 10 + (__DATE__ [5] - '0')) \
#define	BUILD_MONTH
#define	BUILD_HOUR   ( (__TIME__ [0] - '0')*10 + (__TIME__ [1] - '0') )
#define	BUILD_MINUTE   ( (__TIME__ [3] - '0')*10 + (__TIME__ [4] - '0') )
#define	BUILD_SECOND   ( (__TIME__ [6] - '0')*10 + (__TIME__ [7] - '0') )
#define	MAX(a, b)   ((a) > (b) ? (a) : (b))
#define	MIN(a, b)   ((a) < (b) ? a : b)
#define	BLOCK_OVERHEAD   sizeof(PACKET)
#define	BLOCK_OFFSET   sizeof(PACKET)
#define	SIZE_ACTUAL(x)   ((x) & ~0x1)
#define	SIZE_IS_USED(x)   ((x) & 0x1)
#define	HEAP_END(x, y)   ((PACKET *)((char *)(x)+((y))-sizeof(PACKET)))
#define	ASSERT_HEAP(i, h)    if ( (i) < (h) ) prg_exit ("Insufficient heap");
#define	prg_exit(s)
#define	tpFormatOutputFunc   tpFormatOutputFunc
#define	tpOutputFunc   tpOutputFunc
#define	tpWriteString   tpWriteString
#define	tpWriteChar   tpWriteChar
#define	tpReadChar   tpReadChar
#define	MessageLogFxn_type   tpFormatOutputFunc
#define	T_Handle   T_Handle
#define	COM_DEV_CCS   0
#define	COM_DEV_UART   1
#define	COM_DEV_USB   2
#define	COM_DEV_NET   3
#define	COM_DEV_TELNET   4
#define	COM_DEV_FILE   5
#define	COM_DEV_CDC   6
#define	T_ComDevice   T_ComDevice
#define	tpInputParser   tpInputParser
#define	BUFFEROVERFLOW_ERROR   1

Typedefs
typedef int(*	tpFormatOutputFunc) (const char *,...)
typedef int(*	tpOutputFunc) (const char *,...)
typedef void(*	tpWriteString) (const char *)
typedef int32_t(*	tpWriteChar) (char)
typedef int32_t(*	tpReadChar) (char *)
typedef void *	T_Handle
typedef int16_t(*	tpInputParser) (T_ComDevice *, char)

Enumerations
enum	FUNC_RETURN { FR_OK = 0, FR_SKIPPED, FR_ERROR, FR_TIMEDOUT }

Functions
void	config_std_output (void *output)
	configure standard output stream More...
void	PrintExitCode (void)
	Show a descriptive error message on exit. More...
void	AppInit (uint32_t dsp_clock)
	Initialize application. More...
void	AppCleanup (void)
	Disable interrupts, DMA, timer etc. More...
uint32_t	progress (uint32_t done, uint32_t left, uint32_t bad)
char *	num2str (int32_t num, char *buffer, int32_t min, int hexmode)
	convert a 32bit integer to string More...
_CODE_ACCESS void	memmap (uint32_t heap_mem_size)
	show current dynamic memory allocation map More...
uint32_t	GetFreeHeapSize (void)
	determine free heap size More...

Variables
_DATA_ACCESS int	_SYSMEM_SIZE
uint32_t	exit_code
const char *	exit_string
char *	exit_file
uint32_t	exit_line
char *	program_name
const char *	FRMessages []
PACKET	_sys_memory
_DATA_ACCESS int	_memory_size
uint32_t	initial_heap_size

Detailed Description

                          _         _             _
                       __| |    ___(_) ____ _ __ | |_
                      / _` |   / __| |/ _` | '_ \| __|
                     | (_| | _ \__ \ | (_| | | | | |_
                      \__,_|(_) ___/_|\__, |_| |_|\__|
                     Signalprocessing |___/ Technology

Author

D.SignT GmbH & Co. KG, Claus Hermbusche

Version

2.91

Date

2019-04-17

Macro Definition Documentation

#define COMMON_CODE_SECTION   ".commontext"

#define PRAGMA

(

x

)

_Pragma(#x)

#define LOOP_COUNT_INFO	(		min,
			multiple
	)		PRAGMA(MUST_ITERATE(min,,multiple))

#define VAR_IN_SECTION	(		var,
			section
	)		PRAGMA(DATA_SECTION(var, #section))

#define PTR_IS_ALIGNED	(		ptr,
			pow2
	)		_nassert(((uint32_t) (ptr) & (pow2)-1) == 0);

#define CSPRAGMA	(		f,
			s
	)		PRAGMA(CODE_SECTION(f, s))

#define _CPP_extern_open_

#define _CPP_extern_close_

#define NULL   ((void *)UINT32_C(0))

#define _CODE_ACCESS   far

#define _DATA_ACCESS   far

#define UNREFERENCED_PARAMETER

(

P

)

((P)=(P)) \

suppresses warnings about params not used

Examples:

Blocksend.c, BoardSpecific.c, Echo.c, Multicast.c, NetTest.c, and Receive.c.

#define UNUSED_PARAMETER

(

P

)

((void)(P)) \

suppresses warnings about params not used

#define BUILD_YEAR

Value:

((((__DATE__ [7] - '0') * 10 + (__DATE__ [8] - '0')) * 10 \
                    + (__DATE__ [9] - '0')) * 10 + (__DATE__ [10] - '0')) \

build year macro. use to initialize timer variables or for descriptive outputs

#define BUILD_DAY   ((__DATE__ [4] == ' ' ? 0 : __DATE__ [4] - '0') * 10 + (__DATE__ [5] - '0')) \

build day macro. use to initialize timer variables or for descriptive outputs

#define BUILD_MONTH

Value:

(  __DATE__ [2] == 'n' ? (__DATE__ [1] == 'a' ? 1 : 6)   \
                       : __DATE__ [2] == 'b' ? 2                               \
                       : __DATE__ [2] == 'r' ? (__DATE__ [0] == 'M' ? 3 : 4)   \
                       : __DATE__ [2] == 'y' ? 5                               \
                       : __DATE__ [2] == 'l' ? 7                               \
                       : __DATE__ [2] == 'g' ? 8                               \
                       : __DATE__ [2] == 'p' ? 9                               \
                       : __DATE__ [2] == 't' ? 10                              \
                       : __DATE__ [2] == 'v' ? 11 : 12 )                       \

build month macro. use to initialize timer variables or for descriptive outputs

#define BUILD_HOUR   ( (__TIME__ [0] - '0')*10 + (__TIME__ [1] - '0') )

build hour macro. use to initialize timer variables or for descriptive outputs

#define BUILD_MINUTE   ( (__TIME__ [3] - '0')*10 + (__TIME__ [4] - '0') )

build minute macro. use to initialize timer variables or for descriptive outputs

#define BUILD_SECOND   ( (__TIME__ [6] - '0')*10 + (__TIME__ [7] - '0') )

build second macro. use to initialize timer variables or for descriptive outputs

#define MAX	(		a,
			b
	)		((a) > (b) ? (a) : (b))

#define MIN	(		a,
			b
	)		((a) < (b) ? a : b)

#define BLOCK_OVERHEAD   sizeof(PACKET)

#define BLOCK_OFFSET   sizeof(PACKET)

#define SIZE_ACTUAL

(

x

)

((x) & ~0x1)

#define SIZE_IS_USED

(

x

)

((x) & 0x1)

#define HEAP_END	(		x,
			y
	)		((PACKET *)((char *)(x)+((y))-sizeof(PACKET)))

#define ASSERT_HEAP	(		i,
			h
	)		if ( (i) < (h) ) prg_exit ("Insufficient heap");

HEAP check

Examples:

Blocksend.c, Chat.c, DHCPTest.c, DNSTest.c, Echo.c, FTPClient.c, FTPServer.c, HTTPdynamic.c, HTTPjava.c, HTTPsimple.c, Multicast.c, NetTest.c, Ping.c, Ping2.c, PServer.c, Receive.c, Send.c, SMTP.c, SNTPTest.c, and Telnet.c.

#define prg_exit

(

s

)

Value:

{ \
    exit_string = s; \
    exit_line = __LINE__; \
    exit_file = __FILE__; \
    exit (1); \
}

we use a macro rather than a function to log file and line

Examples:

Blocksend.c, BoardSpecific.c, Chat.c, Echo.c, FTPServer.c, HTTPdynamic.c, HTTPjava.c, HTTPsimple.c, Multicast.c, NetTest.c, Receive.c, Send.c, SMTP.c, and Telnet.c.

#define tpFormatOutputFunc   tpFormatOutputFunc

#define tpOutputFunc   tpOutputFunc

#define tpWriteString   tpWriteString

#define tpWriteChar   tpWriteChar

#define tpReadChar   tpReadChar

#define MessageLogFxn_type   tpFormatOutputFunc

#define T_Handle   T_Handle

#define COM_DEV_CCS   0

#define COM_DEV_UART   1

Examples:

BoardSpecific.c.

#define COM_DEV_USB   2

#define COM_DEV_NET   3

#define COM_DEV_TELNET   4

#define COM_DEV_FILE   5

#define COM_DEV_CDC   6

#define T_ComDevice   T_ComDevice

#define tpInputParser   tpInputParser

#define BUFFEROVERFLOW_ERROR   1

Examples:

BoardSpecific.c.

Typedef Documentation

typedef int(* tpFormatOutputFunc) (const char *,...)

Message log function. E.g. printf() or CPrintf()

typedef int(* tpOutputFunc) (const char *,...)

typedef void(* tpWriteString) (const char *)

typedef int32_t(* tpWriteChar) (char)

typedef int32_t(* tpReadChar) (char *)

typedef void* T_Handle

a general handle to a peripheral

typedef int16_t(* tpInputParser) (T_ComDevice *, char)

Enumeration Type Documentation

enum FUNC_RETURN

function return value

Enumerator
FR_OK
FR_SKIPPED
FR_ERROR
FR_TIMEDOUT

{

Function Documentation

void config_std_output

(

void *

output

)

Parameters

output

- new output stream

Returns

nothing

{
    _out_stream = (tpOutputFunc)(uint32_t)output;
}

void PrintExitCode

(

void

)

Parameters

-

Returns

nothing

Print descriptive exit message. This function uses global pointer to exit string. Exit string is set by function prg_exit()

See also

exit_code, exit_string, prg_exit()

{
#ifdef _CPRINTF_H_
    CPrintfActivateOutput();
#endif

    /***************************************************************************
     in case of cprintf buffer overflow a printf is not possible
     set LEDs to signal exit status
    ***************************************************************************/
    if (exit_code != BUFFEROVERFLOW_ERROR)
    {
        /***********************************************************************
         print exit code
        ***********************************************************************/

        if (exit_string!=NULL)
            _out_stream (COMMON_EXIT,exit_file, exit_line, exit_string);

        _out_stream (COMMON_PROGRAM_HALTED);

        /***********************************************************************
         if necessary switch LED on to signal certain errors
        ***********************************************************************/
        // if ( (exit_code == OUT_OF_MEMORY_ERROR )
        // {
            // LED_on (1);
        // }

    }
    else
    {
        fputs (COMMON_BUFFER_OVERFLOW, stderr);

        /***********************************************************************
         switch all LEDs on if printing is impossible
        ***********************************************************************/
        LED_on (0);
        LED_on (1);
        LED_on (2);
        LED_on (3);
    }

    /***************************************************************************
     clean-up application, stop timers, DMA, close handles etc.
    ***************************************************************************/
    AppCleanup();

    return;
}

void AppInit

(

uint32_t

dsp_clock

)

Parameters

dsp_clock

[Hz]

Returns

nothing

Application Initialization Code
Put all your initialization code into this central function. To make the CPrintf() function work as well in your initialization code called from here CPrintf_select_output() should be moved here too.

Examples:

Blocksend.c, Chat.c, DHCPTest.c, DNSTest.c, Echo.c, FTPClient.c, FTPServer.c, HTTPdynamic.c, HTTPjava.c, HTTPsimple.c, Multicast.c, NetTest.c, Ping.c, Ping2.c, PServer.c, Receive.c, Send.c, SMTP.c, SNTPTest.c, and Telnet.c.

{
    /***************************************************************************
     locals
    ***************************************************************************/

    /***************************************************************************
     global disable interrupts
    ***************************************************************************/
    _disable_interrupts();

    /***************************************************************************
     calculate configured heap size
    ***************************************************************************/
#if (defined(USE_DSPBIOS) || defined(USE_SYSBIOS))
    initial_heap_size = GetFreeHeapSize();
#else
    initial_heap_size = ((uint32_t)&_SYSMEM_SIZE);
#endif

    /***************************************************************************
     basic initialisation
    ***************************************************************************/
    BoardAppInit (dsp_clock);

    /***************************************************************************
      install exit function
    ***************************************************************************/
    atexit (PrintExitCode );

    /***************************************************************************
      initialize board peripherals
    ***************************************************************************/
    BoardPeripheralInit();

    /***************************************************************************
      initialize LEDs
    ***************************************************************************/
    LED_init ();

    /***************************************************************************
      initialize KEYs
    ***************************************************************************/
    KEY_init ();

#ifdef INC_CPRINTF
    /***************************************************************************
     let the standard outputs go to our CPrintf device
    ***************************************************************************/
    config_std_output((void *)CPrintf);
#endif
}

void AppCleanup

(

void

)

Parameters

-

Returns

nothing

Application Cleanup Code at exit
This function is called on exit to cleanup running processes like interrupts and DMA, flush opened files, close handles

Examples:

FTPServer.c.

{

    /***************************************************************************
      close all peripherals
    ***************************************************************************/
    BoardPeripheralClose ();

    /***************************************************************************
      disable interrupt
    ***************************************************************************/
    _disable_interrupts();
}

uint32_t progress	(	uint32_t	done,
		uint32_t	left,
		uint32_t	bad
	)

{
    /***************************************************************************
      locals
    ***************************************************************************/
    static uint32_t old = UINT32_C(101);
    int32_t temp;
    int32_t total = (int32_t)done + (int32_t)left;

    if (total==INT32_C(0))
    {
        old = UINT32_C(101);
        return (UINT32_C(0)); // prevent division by zero
    }
    temp =  (int32_t)(done *100.0 / (float)(total));
    if ( old != temp )
    {
        old = temp;
        _out_stream ("\b\b\b\b\b\b %3d %%", old );
        if ( old == INT32_C(100) )
        {
            temp = (int32_t)bad;
            if ( temp > 0 ) _out_stream (" - %d bad blocks - ", bad);
            old = UINT32_C(101);
        } // if
    } // if

    return (UINT32_C(1));
}

char* num2str	(	int32_t	num,
		char *	buffer,
		int32_t	min,
		int	hexmode
	)

Parameters

num	- number to convert
*buffer	- pointer to string buffer
min	- reserved number of digits in string, 0 means automatic
hexmode	- 1: switch to hex mode

Returns

pointer to string buffer

{
    /***************************************************************************
      Locals
    ***************************************************************************/
    char* s = buffer;
    char const digit[] = "0123456789abcdef";
    uint32_t shifter;
    int base = hexmode?16:10;
    uint32_t i = (uint32_t)num;

    /***************************************************************************
      process sign and build absolute value, if not in hex mode
    ***************************************************************************/
    if ( ( !hexmode ) && ( num < INT32_C(0) ) )
    {
        s++;
        i = (uint32_t)(num * -1);
    } // if

    /***************************************************************************
      move to end
    ***************************************************************************/
    shifter = i;
    do
    {
        ++s;
    } while ( shifter /= base );

    /***************************************************************************
     check reserved number of digits if not zero
    ***************************************************************************/
    if ( min )
    {
        if ( (s-buffer) < min )
        {
            s = buffer + min;
        } // if
    } // if

    /***************************************************************************
      convert to string
    ***************************************************************************/
    *s = '\0';
    do
    {
        *--s = digit[i%base];
    } while ( i /= base );

    /***************************************************************************
      insert sign
    ***************************************************************************/
    if ( ( !hexmode ) && ( num < INT32_C(0) ) )
    {
        *--s = '-';
    } // if

    /***************************************************************************
      fill in leading blanks, if necessary
    ***************************************************************************/
    while ( s > buffer )
    {
        *--s = ' ';
    } // if


    return (buffer);
}

_CODE_ACCESS void memmap

(

uint32_t

heap_mem_size

)

This function is useful to show memory fragmentation and to detect memory leaks

Parameters

heap_mem_size

- configured heap size

Returns

-

Note

Taken from TI's RTS source

{
    /***************************************************************************
      Locals
    ***************************************************************************/
    PACKET *current;
    PACKET *heap_end;
    uint32_t free_block_num     = UINT32_C(0);
    uint32_t free_block_space   = UINT32_C(0);
    uint32_t free_block_max     = UINT32_C(0);
    uint32_t used_block_num     = UINT32_C(0);
    uint32_t used_block_space   = UINT32_C(0);
    uint32_t used_block_max     = UINT32_C(0);
    volatile uint32_t size;
    volatile int used;
    current = (PACKET *)&_sys_memory;
    heap_end = HEAP_END(current,heap_mem_size);

    /*-----------------------------------------------------------------------*/
    /* LOOP THROUGH ALL PACKETS                                              */
    /*-----------------------------------------------------------------------*/
    while (current < heap_end)
    {
        size = (uint32_t)(SIZE_ACTUAL(current->packet_size));
        used = (int)(SIZE_IS_USED(current->packet_size));

        _out_stream (">> Used:%d size:%"PRId32" addr:%"PRIx32"\r\n", used, size, (char*)current+ BLOCK_OVERHEAD);

        if (used)
        {
            used_block_num++;
            used_block_space += size;
            used_block_max   = MAX(used_block_max, size);
        }
        else
        {
            free_block_num++;
            free_block_space += size;
            free_block_max   = MAX(free_block_max, size);
        }
        current = (PACKET *)((char *)current + size + BLOCK_OFFSET);
    }

    _out_stream ("fr_nm:%"PRIx32" fr_sp:%"PRIx32" fr_mx:%"PRIx32" us_nm:%"PRIx32" us_sp:%"PRIx32" us_mx:%"PRIx32" ovr:%"PRIx32"\r\n",
       free_block_num, free_block_space, free_block_max,
       used_block_num, used_block_space, used_block_max,
       (free_block_num + used_block_num) * BLOCK_OVERHEAD);
}

uint32_t GetFreeHeapSize

(

void

)

Parameters

-

Returns

free heap size

This function determines the largest free heap block

Parameters

-

Returns

free heap size

Examples:

DHCPTest.c.

{
    /***************************************************************************
     locals
    ***************************************************************************/
    uint32_t sz = UINT32_C(1);
    void* p;
    int m = 0, i;

    for (;;)
    {
        p = malloc (sz);
        if ( p == NULL )
            break;
        free (p);
        m++;
        sz <<= 1;
    }

    if ( !m )
        return (0);

    m--;
    sz = ((uint32_t)1) << m;

    for ( i=m-1; i>=0; i--)
    {
        uint32_t s = ((uint32_t)1) << i;
        p = malloc (sz | s);
        if ( p != NULL )
        {
            free (p);
            sz |= s;
        }
    }
    return (sz);
}

Variable Documentation

_DATA_ACCESS int _SYSMEM_SIZE

exit_code

Variable to hold exit code

exit codes => system error codes to signal fatal errors

See also

prg_exit(), exit_string, PrintExitCode()

Examples:

BoardSpecific.c.

const char* exit_string

exit string => global variable set in prg_exit() to the current exit message

See also

prg_exit(), exit_code, PrintExitCode()

char* exit_file

exit file => global variable set in prg_exit() to the current exit file

See also

prg_exit(), exit_code, PrintExitCode()

uint32_t exit_line

exit line => global variable set in prg_exit() to the current exit line

See also

prg_exit(), exit_code, PrintExitCode()

char* program_name

Examples:

Blocksend.c, Chat.c, DHCPTest.c, DNSTest.c, Echo.c, FTPClient.c, Multicast.c, Ping.c, Ping2.c, PServer.c, Send.c, SNTPTest.c, and Telnet.c.

const char* FRMessages[]

function return messages

Examples:

SMTP.c.

PACKET _sys_memory

_DATA_ACCESS int _memory_size

uint32_t initial_heap_size

configured heap size

Examples:

Blocksend.c, Chat.c, DHCPTest.c, DNSTest.c, Echo.c, FTPClient.c, FTPServer.c, HTTPdynamic.c, HTTPjava.c, HTTPsimple.c, Multicast.c, NetTest.c, Ping.c, Ping2.c, PServer.c, Receive.c, Send.c, SMTP.c, SNTPTest.c, and Telnet.c.