weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files | Data Structures | Defines | Typedefs | Variables
Common types and helpers
+ + Application (layer) support + +

Overview

Some weAutSys of types and helper macros and functions have common usages in more than one (application) module.

Clearly, in this category fall definitions due to special treatment sometimes required by parts of the software toolchain (Eclipse, SVN, GCC, Doxygen, AVR...). To give just two examples:
Doxygen gets problems with some AVR / Atmel related attributes (that clearly fall outside any C standard).
Some Eclipse versions have problems to follow the quite complicated macro expansion and include file trees controlled by the µController type in the AVR GCC lib.

See also the text blocks and utilities.

Files

file  common.h
 

weAutSys' common types and helper functions


file  config.h
 

weAutSys' configuration settings


file  ll_common.h
 

weAutSys' basic common types and helper functions


Data Structures

struct  cliThr_data_t
 The organisational data for a command line interpreter (CLI) thread. More...
struct  hierThr_data_t
 The organisational data for a small thread hierarchy. More...
struct  mThr_data_t
 State data for a thread (minimal) More...
struct  outFlashTextThr_data_t
 The organisational data for a flash strings array output thread. More...
struct  thr_data_t
 State data for a thread (universal variable type) More...
struct  u16div_t
 Two unsigned words intended for quotient and remainder. More...
struct  u8div_t
 Two unsigned bytes intended for quotient and remainder. More...
union  ucnt16_t
 A medium (16 bit) value in different resolutions. More...
union  ucnt32_t
 A big (32 bit) value in different resolutions. More...

Defines

#define ADDR_T
 flash address is 16 bit for this µController
#define ADDR_U
 flash address is 16 bit for this µController
#define addr_v
 flash address is 16 bit for this µController
#define APP_END
 The end of the application flash area (as byte address + 1)
#define BEL
 The bell code.
#define BOOTL_BEG
 The start address of the bootloader (area)
#define BOOTSIZE   4096
 The (maximum) boot size in bytes.
#define BS
 The back space code.
#define CR
 The carriage return code.
#define ESC
 The Escape code.
#define EXTRA_THR_ST_SZ   158
 Size of (extra) thread state data.
#define FCPU_S
 The CPU clock frequency (as string)
#define FF
 The form feed code.
#define FOLLOW_UP
 Follow up string marker for outFlashTextThr_data_t.
#define GN_LED_INV
 invert gn LED: ! ; no invert: empty
#define HBYTE(x)
 Get the high byte (of a 16 bit value)
#define HT
 The horizontal tab code.
#define LARGE_MEMORY   0
 The flash memory byte address type.
#define LBYTE(x)
 Get the low byte (of a 16 bit value)
#define LEN_OF_CLITHR_LINE
 The maximum number of characters in cliThr_data_t.line.
#define LF
 The linefeed code.
#define OFF
 A boolean false respectively off.
#define ON
 A boolean true respectively on.
#define PLATFORM_S
 The platform name (as string)
#define RD_LED_INV
 invert rd LED: ! ; no invert: empty
#define SIZE_OF_BIGGEST_APPSTATE   164
 The size of the biggest application state structure used in bytes.
#define STD_BAUD   38400
 Standard resp. used baudrate.
#define SYST_AUT   "Albrecht Weinert <a-weinert.de> "
 The runtime's author.
#define SYST_BLD
 The runtime's system build and time.
#define SYST_COP
 The runtime's copyright notice.
#define SYST_DAT   "$Date: 2017-01-25 17:49:03 +0100 (Mi, 25 Jan 2017) $"
 This file's last modification date (SVN)
#define SYST_MOD
 This file's last modifier respectively SVN author.
#define SYST_NAM   "weAutSys"
 The runtime's name.
#define SYST_REV
 The runtime's revision.
#define TRAMPOLIN_USE   1
 The trampolin hack is used.
#define USART_IN_APP_WITH_INT
 UART uses no interrupt in application.
#define VT
 The vertical tab code.

Defines due to tools

#define INFLASH(decl)
 Alternative declaration for flash memory.
#define INEEPROM(decl)
 Declaration for EEPROM memory.
#define STR(leMac)
 A macro value as string.

Typedefs

typedef ptfnct_tfun_t )(struct thr_data_t *thrData)
 Type of a protothread function (struct thr_data_t *)
typedef ptfnct_tfunA_t )(struct cliThr_data_t *thrData)
 Type of a protothread function (cliThr_data_t *)
typedef ptfnct_tfunU_t )(struct mThr_data_t *uthr_data)
 Type of a protothread function (struct mThr_data_t *)
typedef ptfnct_tfunV_t )(void)
 Type of a protothread function (void)
typedef funU_tp2ptFun
 Pointer to a protothread function (struct mThr_data_t *)
typedef funA_tp2ptFunA
 Pointer to a protothread function (cliThr_data_t *)
typedef fun_tp2ptFunC
 Pointer to a protothread function (struct thr_data_t *)
typedef funV_tp2ptFunV
 Pointer to a protothread function (void)

Variables

char const bLF1 []
 1 blank, 1 linefeed 0 terminated in flash memory
char const bLF2 []
 1 blank, 2 linefeed 0 terminated in flash memory
char const l4nefeeds []
 A short string with just one blank and four linefeeds in flash memory.

Define Documentation

#define SIZE_OF_BIGGEST_APPSTATE   164

The size of the biggest application state structure used in bytes.

The type of the application state that is to be stored in the uip_conn structure may vary. This number shall be the maximum size of all application states.

Note:
This would have to be about 2 Kbyte as soon as A.D.'s HTTP implementation is used. This (one of the weakest parts of uIP) will can not be handled this way for small embedded systems.
See also:
uip_conn
#define FOLLOW_UP

Follow up string marker for outFlashTextThr_data_t.

See also:
outFlashTextThr_data_t
Examples:
main.c.
#define SYST_NAM   "weAutSys"

The runtime's name.

  See also:   SYST_DAT

#define SYST_DAT   "$Date: 2017-01-25 17:49:03 +0100 (Mi, 25 Jan 2017) $"

This file's last modification date (SVN)

This file's subversion (SVN) modification date and revision number are taken as the weAutSys runtime's revision data.

The value is a "quoted" string.

  See also:   DEFAULT_START_TIME SYST_REV SYST_MOD

#define SYST_MOD

This file's last modifier respectively SVN author.

The value is a "quoted" string.

  See also:   DEFAULT_START_TIME SYST_REV SYST_DAT

#define TRAMPOLIN_USE   1

The trampolin hack is used.

This value is true (!= 0) if the trampolin hack (+ linker relaxation) is used (and hopefully works) on large ATmegas with more than 128K flash.

As of January 2014 this is a "feature" of arv-gcc, thus avoiding the introduction of 24 bit pointers (for label as value) as well as a correct and consistent handling of EIND.

This marco defines a property of the (AVR gcc) toolchain. The only place it is used (or prepared to be used as of Nov. 2014) is the weAutSys implementation of protothreads.

#define INFLASH (   decl)

Alternative declaration for flash memory.

This macro is a replacement for the use of the PROGMEM macro.

One can end an INFLASH declaration by just a (;) semicolon. But as it is for final flash / program memory variables a declaration is usually accompanied by an initialiser, like in:

     INFLASH(char flashString[]) = "in program memory and only there";

Most C implementations, like the GNU C Compilers and tools (GCC) used here, can't handle Harvard architecture in a smooth consistent and portable way. Instead of healing that, ugly helper constructs (<avr/pgmspace.h>) have been invented and, alas, must be used. Among other problems their usage then causes tooling problems (Doxygen, Eclipse).

Internal: In case of macro DOXYGEN defined INFLASH just leaves decl without extra attribute. (Doxygen hates PROGMEM.)

Hint: The pgm_read_byte(address) expression has to be used to access INFLASEHed final variables. This works only in the range 0..64k-1. If INFLASEHed items happen to life above 64k pgm_read_byte_far(longByteAddress) has to be used. longByteAddress will not be constructed correctly by avr-gcc C pointer handling in most cases.

Parameters:
decla (standard), i.e. "type name", variable declaration without further modifiers
See also:
INEEPROM
Examples:
main.c.
#define INEEPROM (   decl)

Declaration for EEPROM memory.

This macro is used to define variables in the EEPROM usually for generating individualised .hex files for configuration settings (like MAC address etc.) If, for example, the source individEEP.c contains such settings to be in the EEPROM starting at address 0x80 one would do something like this:

       avr-gcc -c -mmcu=atmega1284p -Wl,--section-start=.eeprom=0x0080 -I.  -I ./include individEEP.c
       avr-objcopy -j .eeprom --change-section-lma .eeprom=128 --no-change-warnings -O ihex individEEP.o  individEEP.hex
       avrdude -p atmega1284p -c avrisp2  -P com4   -U eeprom:w:individEEP.hex:i

One can end an INEEPROM declaration by just a (;) semicolon. But as it is in the end for generating final values for (individualised) EEPROM .hex files the variables defined are usually accompanied by an initialiser, like in the example:

     INEEPROM(uint8_t redundantEndMarker) = 0x77;
Parameters:
decla (standard), i.e. "type name", variable declaration without further modifiers
See also:
INFLASH
Examples:
individEEP.c.
#define STR (   leMac)

A macro value as string.

This macro implements the "stringification" of a marco's value. See gnu.org's GCC documentation (chapter 1.4.4). GCC's stringification has some special rules concerning white space and escapes. Hence for more complicated values the result might not meet the expectations.

Parameters:
leMacthe macro to stringify
#define FCPU_S

The CPU clock frequency (as string)

See the macro F_CPU defined in the makefile.

This is its value as string, normally "20000000" for 20MHz.

#define PLATFORM_S

The platform name (as string)

See the macro (respectively make variable) PLATFORM defined in the makefile.

This is its value as string, that is "weAut_01" and the like.

#define SYST_AUT   "Albrecht Weinert <a-weinert.de> "

The runtime's author.

It is the author's name and his personal domain.
The value is a "quoted" string.

#define SYST_COP
Value:
"Copyright (c) 2014  weinert - automation  \n"\
                 "Prof. Dr.-Ing. Albrecht Weinert,  Bochum  \n"

The runtime's copyright notice.

The value is a two line "quoted" string with trailing linefeed.

#define SYST_BLD

The runtime's system build and time.

It is the time this file was processed by the compiler — or more correct by the pre-processor.

The value is a "quoted" string.

#define HBYTE (   x)

Get the high byte (of a 16 bit value)

This is a helper. It gets second byte of a value (larger than one byte). That would be the high byte of a 16 bit value.

It is expressed by masking the high byte and shifting right by 8. The AVR C Compiler is clever enough to just pick the appropriate byte respectively register as result. So this helper does not harm.

#define LBYTE (   x)

Get the low byte (of a 16 bit value)

This is a helper that just masks the lowest byte of a 16 bit (or larger) value.

  See also:   HBYTE

#define OFF

A boolean false respectively off.

The value of false / off / aus / éteint is 0.

Examples:
main.c.
#define ON

A boolean true respectively on.

The value of true / on / an / démarré is FF... meaning all bits one for any size or type.

Examples:
main.c.
#define LF

The linefeed code.

A LF character is usually the equivalent of \n. LF and CR are counted in the serial input buffer.
The value of LF is 10 respectively 0x0A

#define CR

The carriage return code.

See also:
LF The value of CR is 13 respectively 0x0D
#define BEL

The bell code.

A BEL character is produces an audible (or visible) signal but no visible / printable character output (not even white space).
BEL my be used by some Telnet software.
The value of BEL is 7

#define BS

The back space code.

BS may be used by some Telnet software to [rfc854]:
moves the (NVT printer's) print head one character position towards the left margin.
The value of BS is 8

#define HT

The horizontal tab code.

HT may be used by some Telnet software to [rfc854]
move the (NVT printer's) print head to the next horizontal tab stop. It remains unspecified how either party determines or establishes where such tab stops are located. [rfc854 cite end]
The value of HT is 9

#define VT

The vertical tab code.

VT may be used by some Telnet software to [rfc854]
move the (NVT printer's) print head to the next vertical tab stop. It remains unspecified how either party determines or establishes where such tab stops are located. [rfc854 cite end]
The value of VT is 11 (0x0B)

#define FF

The form feed code.

FF may be used by some Telnet software to [rfc854]
move the (NVT printer's) print head to the top of the next page, keeping the same horizontal position. [rfc854 cite end]
The value of FF is 12 (0x0C)

#define ESC

The Escape code.

ESC may be used as a sync character e.g. by some bootloader software.

The value of ESC is 0x1B

#define APP_END

The end of the application flash area (as byte address + 1)

This value is the end of the Read-While-Write (RWW) section in flash + 1 as byte address. For an ATmega 1284 this is e.g.:
    122880 = 1E000 = F000 * 2
For an ATmega 2560 this is e.g.:
    253952 = 3E000 = 1F000 * 2

The usage of byte addresses forces more than 16 bit for the address in this case.

The value is ((FLASHEND - BOOTSIZE) + 1)

#define BOOTL_BEG

The start address of the bootloader (area)

This byte address in flash memory is just APP_END.

#define LARGE_MEMORY   0

The flash memory byte address type.

The ATmega's flash memory is a word (16bit) organised program memory in Harvard architecture. Hence a 16 bit program counter is sufficient for a 128 kByte flash (ATmega1284 e.g.). Nevertheless final variables can be placed in flash, too, forcing it to be byte addressable therefore. In that sense LARGE_MEMORY true (not 0) means we need byte addresses larger than 16 bit forcing the address type from 16 to 32 bit.
Note: 24 bit would suffice for all large ATmegas, but C hardly handles that size.

See also:
ADDR_T

Typedef Documentation

typedef ptfnct_t( funV_t)(void)

Type of a protothread function (void)

funV_t is a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking no parameter.

typedef funV_t* p2ptFunV

Pointer to a protothread function (void)

p2ptFunV is a pointer to a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and no parameter.

typedef ptfnct_t( funU_t)(struct mThr_data_t *uthr_data)

Type of a protothread function (struct mThr_data_t *)

funU_t is a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to the basic minimal thread state (mThr_data_t) as parameter.

typedef funU_t* p2ptFun

Pointer to a protothread function (struct mThr_data_t *)

p2ptFun is a pointer to a function returningPT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to the basic minimal thread state (mThr_data_t) as parameter.

typedef ptfnct_t( fun_t)(struct thr_data_t *thrData)

Type of a protothread function (struct thr_data_t *)

fun_t is a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to the common variable type thread state as parameter.

typedef fun_t* p2ptFunC

Pointer to a protothread function (struct thr_data_t *)

p2ptFunC is a pointer to a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to the common variable type thread state (thr_data_t) as parameter.

typedef ptfnct_t( funA_t)(struct cliThr_data_t *thrData)

Type of a protothread function (cliThr_data_t *)

funA_t is a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to a CLI (thread) state (cliThr_data_t) as parameter.

typedef funA_t* p2ptFunA

Pointer to a protothread function (cliThr_data_t *)

p2ptFunA is a pointer to a function returning PT_WAITING, PT_YIELDED, PT_EXITED or PT_ENDED and taking a pointer to a CLI (thread) state (cliThr_data_t) as parameter.


Variable Documentation

char const l4nefeeds[]

A short string with just one blank and four linefeeds in flash memory.

This flash string as all cognates (bLF1, bLF2 and many more) are 0 terminated. As flash strings they are immutable (by all normal and erroneous program means). They should be used whenever their content is asked for to save precious RAM.