WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

libdefs.h

Defines various macros and datatypes that are used in the rest of the library.

 

Function

 


CRITICAL_SECTION

Bracket a section of code that shoud not be interrupted.
Since most ATMegas are 8 bit devices then you must be careful when accessing any memory variable that is greater than 8 bit in size as it will require more than one instruction to read the variable. If the variable is not changed by any interrupt routine then all is OK.
However: if the variable is changed by an interrupt routine then you must do several things:
1. Mark the variable as 'volatile' so that the compiler knows that it always needs to read the current value rather than keeping old copies lying around in registers.
2. Any foreground (ie non-interrupt service) routine that reads the variable must make sure that it is not changed by an interrupt whilst it is being read.
To show you what I mean then assume you have a 16 bit number that is also changed in an interrput then you would need to declare it as:
volatile uint16_t myNumber;
Since a 16 bit number is two bytes then it requires two instructions to read it (low byte first, then high byte). Lets assume it currently holds the number 255 (ie High byte=0, low byte=255).
Assume we try to read it like this:
uint16_t myCopy = myNumber;
Then the compiler will generate code to read the low byte first (ie 255) then the high byte (ie 0) but since it requires two instructions then there is nothing to stop an interrupt happening in the middle. Lets assume that the interrupt routine adds one to the variable:
myNumber++;
so that the low byte is now 0 and the high byte is now 1.
This causes a major problem as our main code has read the old low byte (255) and then reads the new high byte (1) - so the answer it gets is 1*256 + 255 = 511. Of course this is neither the old number (255) nor the new number (256) - its a mixture of both!!!!
You can prevent this by using:
CRITICAL_SECTION{
    uint16_t myCopy = myNumber;
}
During the bracketed section then all interrupts will be disabled meaning that you read the proper values but this code should be kept as small, ie quick, as possible. If you leave interrupts disabled for too long then you may miss key events such as a character arriving on a UART etc.

CRITICAL_SECTION_START

Deprecated - use CRITICAL_SECTION instead

CRITICAL_SECTION_END

Deprecated - use CRITICAL_SECTION instead

uint8_t READMEMBYTE(rom,char_ptr)

This macro will read a byte either from ROM or from RAM given the following parameters:-
rom - If FALSE it reads from RAM, if TRUE then it assumes the byte was declared to be in ROM
char_ptr - The address of the byte you want to read.

MIN(a,b)

This macro takes two numbers as its arguments and will return the smallest one ie the one closest to negative infinity.

MAX(a,b)

This macro takes two numbers as its arguments and will return the largest one ie the one closest to positive infinity.

ABS(x)

This macro takes one number as its arguments and will return the absolute value. ie if the number starts with a '-' then it will change it to a '+'.

CLAMP(val, min, max)

A macro to clamp a value to be within a given range.
You can use this macro to make sure that a values lies within a given range. For example: if you have a variable called 'value' and you want to make sure that its contents is in the range 10 to 99 then you can use:
value = CLAMP(value, 10, 99);
If the initial value is less than 10 then it will be set to 10. If it is greater than 99 then it will be set to 99.

uint16_t get_uint16(const void* buf,size_t offset)

Returns a 16 bit integer from a buffer.
This assumes the data is stored as least significant byte then most significant byte.
The parameters specify a memory array and a byte offset into that array.

int16_t get_int16(const void* buf,size_t offset)

Returns a 16 bit signed integer from a buffer.
This assumes the data is stored as least significant byte then most significant byte.
The parameters specify a memory array and a byte offset into that array.

uint32_t get_uint32(const void* buf,size_t offset)

Returns a 32 bit integer from a buffer.
This assumes the data is stored from least significant byte to most significant byte.
The parameters specify a memory array and a byte offset into that array.

set_uint16(const void* buf,size_t offset,uint16_t data)

Stores a 16 bit integer into a buffer.
This assumes the data is stored as least significant byte then most significant byte.
The parameters specify a memory array, a byte offset into that array, and the value to be written.

set_uint32(const void* buf,size_t offset,uint32_t data)

Stores a 32 bit integer into a buffer.
This assumes the data is stored from least significant byte thorugh to most significant byte.
The parameters specify a memory array, a byte offset into that array, and the value to be written.

Valid XHTML 1.0 Transitional