Built-in Routines

The mikroC PRO for FT90x compiler provides a set of useful built-in utility functions.

The Lo, Hi, Higher, Highest, LoWord, HiWord routines are implemented as macros. If you want to use these functions you must include built_in.h header file (located in the inlclude folder of the compiler) into your project.

The Delay_us and Delay_ms routines are implemented as “inline”; i.e. code is generated in the place of a call, so the call doesn’t count against the nested call limit.

The Vdelay_ms, Vdelay_advanced_ms, Delay_Cyc, Delay_Cyc_Long, Get_Fosc_kHz and Get_Fosc_Per_Cyc are actual C routines. Their sources can be found in Delays.c file located in the uses folder of the compiler.

Lo

Prototype

#define Lo(param) ((char *)&param)[0]

Description

The function returns low byte of param. The function does not interpret bit patterns of param – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

Low byte of param, bits 7..0.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = Lo(d);  // Equals 0x78

Lo(d) = 0xAA; // d equals 0x123456AA
Notes

None.

Hi

Prototype

#define Hi(param) ((char *)&param)[1]

Description

The function returns high byte of param. The function does not interpret bit patterns of param – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

High byte of param, bits 15..8.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = Hi(d);  // Equals 0x56

Hi(d) = 0xAA; // d equals 0x1234AA78
Notes

None.

Higher

Prototype

#define Higher(param) ((char *)&param)[2]

Description

The function returns higher byte of param. The function does not interpret bit patterns of param – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

Higher byte of param, bits 23..16.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = Higher(d);  // Equals 0x34

Higher(d) = 0xAA; // d equals 0x12AA5678
Notes

None.

Highest

Prototype

#define Highest(param) ((char *)&param)[3]

Description

The function returns highest byte of param. The function does not interpret bit patterns of param – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

Highest byte of param, bits 31..24.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = Highest(d);  // Equals 0x12

Highest(d) = 0xAA; // d equals 0xAA345678
Notes

None.

LoWord

Prototype

unsigned int LoWord(unsigned long param);

Description

The function returns low word of param. The function does not interpret bit patterns of param – it merely returns 16 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

Low word of param, bits 15..0.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = LoWord(d);  // Equals 0x5678

LoWord(d) = 0xAAAA; // d equals 0x1234AAAA
Notes

None.

HiWord

Prototype

unsigned int HiWord(unsigned long param);

Description

The function returns high word of param. The function does not interpret bit patterns of param – it merely returns 16 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

High word of param, bits 31..16.

Requires

Nothing.

Example
d = 0x12345678; 	
tmp = HiWord(d);  // Equals 0x1234

HiWord(d) = 0xAAAA; // d equals 0xAAAA5678
Notes

None.

LoLongWord

Prototype

#define LoLongWord(param) ((unsigned long*)¶m)[0]

Description

The function returns low longword of param. The function does not interpret bit patterns of param – it merely returns 32 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

Low longword of param, bits 31..0.

Requires

Nothing.

Example
d = 0x1122334455667788;
tmp = LoLongWord(d);  // Equals 0x55667788

LoLongWord(d) = 0xAAAAAAAA; // d equals 0x11223344AAAAAAAA
Notes

None.

HiLongWord

Prototype

#define HiLongWord(param) ((unsigned long*)¶m)[1]

Description

The function returns high longword of param. The function does not interpret bit patterns of param – it merely returns 32 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • param: input number.
Returns

High word of param, bits 63..32.

Requires

Nothing.

Example
d = 0x1122334455667788;
tmp = HiLongWord(d);  // Equals 0x11223344

HiLongWord(d) = 0xAAAAAAAA; // d equals 0xAAAAAAAA55667788
Notes

None.

Delay_us

Prototype

void Delay_us(const unsigned long time_in_us);

Description

Creates a software delay in duration of time_in_us microseconds.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • time_in_us: delay time in microseconds. Valid values: constant values, range of applicable constants depends on the oscillator frequency
Returns

Nothing.

Requires

Nothing.

Example
Delay_us(10);  /* Ten microseconds pause */
Notes

None.

Delay_ms

Prototype

void Delay_ms(const unsigned int time_in_ms);

Description

Creates a software delay in duration of time_in_ms milliseconds.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters
  • time_in_ms: delay time in milliseconds. Valid values: constant values, range of applicable constants depends on the oscillator frequency
Returns

Nothing.

Requires

Nothing.

Example
Delay_ms(1000);  /* One second pause */
Notes

For generating delays with variable as input parameter use the Vdelay_ms routine.

Vdelay_ms

Prototype

void Vdelay_ms(unsigned Time_ms);

Description

Creates a software delay in duration of Time_ms milliseconds. Generated delay is not as precise as the delay created by Delay_ms.

Parameters
  • Time_ms: delay time in milliseconds
Returns

Nothing.

Requires

Nothing.

Example
unsignedpause = 1000;
...
Vdelay_ms(pause);  // ~ one second pause
Notes

Vdelay_ms is a library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

VDelay_Advanced_ms

Prototype

void VDelay_Advanced_ms(unsigned time_in_ms, unsigned Current_Fosc_kHz);

Description

Creates a software delay in duration of time_in_ms milliseconds (a variable), for a given oscillator frequency. Generated delay is not as precise as the delay created by Delay_ms.

Parameters
  • Time_ms: delay time in milliseconds
  • Current_Fosc_kHz: desiredoscillator frequency
Returns

Nothing.

Requires

Nothing.

Example
pause = 1000;
fosc = 10000;

VDelay_Advanced_ms(pause, fosc);  // Generates approximately one second pause, for a oscillator frequency of 10 MHz
Notes

Note that VDelay_Advanced_ms is library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Delay_Cyc

Prototype

void Delay_Cyc(unsigned long cycles_div_by_10));

Description

Creates a delay based on MCU clock.

Parameters
  • cycles_div_by_10: number of cycles divided by 10
Returns

Nothing.

Requires

Nothing.

Example
Delay_Cyc(10);  // 1 cycles pause
Notes

Delay_Cyc is a library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Delay_Cyc_Long

Prototype

void Delay_Cyc_Long(unsigned long CycNo);

Description

Creates a delay based on MCU clock. Delay lasts for CycNo MCU clock cycles.

Parameters
  • CycNo: number of cycles
Returns

Nothing.

Requires

Nothing.

Example
Delay_Cyc_Long(16394);  // 16394 cycles pause
Notes

Delay_Cyc_Long is a library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Clock_kHz

Prototype

unsigned long Clock_kHz();

Description

Function returns device clock in kHz, rounded to the nearest integer.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters

None.

Returns

Device clock in kHz, rounded to the nearest integer.

Requires

Nothing.

Example
unsigned long clk;
...
clk = Clock_kHz();
Notes

None.

Clock_Mhz

Prototype

unsigned long Clock_MHz();

Description

Function returns device clock in MHz, rounded to the nearest integer.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Parameters

None.

Returns

Device clock in MHz, rounded to the nearest integer.

Requires

Nothing.

Example
unsigned long clk;
...
clk = Clock_Mhz();
Notes

None.

Get_Fosc_kHz

Prototype

unsigned long Get_Fosc_kHz();

Description

Function returns device clock in kHz, rounded to the nearest integer.

Note that Get_Fosc_kHz is library function rather than a built-in routine; it is presented in this topic for the sake of c?nvenience.

Parameters

None.

Returns

Device clock in kHz, rounded to the nearest integer.

Requires

Nothing.

Example
unsigned long clk;
...
clk = Get_Fosc_kHz();
Notes

None.

Get_Peripheral_Clock_kHz

Prototype

unsigned int Get_Peripheral_Clock_kHz();

Description

Function returns peripheral clock in kHz, rounded to the nearest integer.

Note that Get_Peripheral_Clock_kHz is library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Parameters

None.

Returns

Periperal clock in kHz, rounded to the nearest integer.

Requires

Nothing.

Example
unsigned long clk;
...
clk = Get_Peripheral_Clock_kHz();
Notes

None.

Get_Fosc_Per_Cyc

Prototype

unsigned int Get_Fosc_Per_Cyc();

Description

Function returns device's clock per cycle, rounded to the nearest integer.

Note that Get_Fosc_Per_Cyc is library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Parameters

None.

Returns

Device's clock per cycle, rounded to the nearest integer.

Requires

Nothing.

Example
unsigned int clk_per_cyc;
...
clk_per_cyc = Get_Fosc_Per_Cyc();
Notes

None.

MEMCPY_B

Prototype

void *MEMCPY_B(void *s1, void *s2, long nn);

Description

Function copies nn bytes from the object pointed to by s2 into the object pointed to by s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the MEMCPY instruction is exactly the same as the standard C memcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

Use this function for all object alignments.

MEMCPY_S

Prototype

void *MEMCPY_S(void *s1, void *s2, long nn);

Description

Function copies nn bytes from the object pointed to by s2 into the object pointed to by s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the MEMCPY instruction is exactly the same as the standard C memcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

MEMCPY_L

Prototype

void *MEMCPY_L(void *s1, void *s2, long nn);

Description

Function copies nn bytes from the object pointed to by s2 into the object pointed to by s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the MEMCPY instruction is exactly the same as the standard C memcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

MEMSET_B

Prototype

void *MEMSET_B(void *s, long c, long n);

Description

Function copies the value of the byte c into each of the first n bytes of the object pointed by s.

The behavior of the MEMSET instruction is exactly the same as the standard C memsety() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s.

Requires

Nothing.

Notes

None.

MEMSET_S

Prototype

void *MEMSET_S(void *s, long c, long n);

Description

Function copies the value of the byte c into each of the first n bytes of the object pointed by s.

The behavior of the MEMSET instruction is exactly the same as the standard C memset() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

MEMSET_L

Prototype

void *MEMSET_L(void *s, long c, long n);

Description

Function copies the value of the byte c into each of the first n bytes of the object pointed by s.

The behavior of the MEMSET instruction is exactly the same as the standard C memset() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STREAMIN_B

Prototype

void *STREAMIN_B(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory.

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

None.

STREAMIN_S

Prototype

void *STREAMIN_S(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STREAMIN_L

Prototype

void *STREAMIN_L(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STREAMINI_B

Prototype

void *STREAMINI_B(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory, with incrementing destination program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

None.

STREAMINI_S

Prototype

void *STREAMINI_S(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory, with incrementing destination program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STREAMINI_L

Prototype

void *STREAMINI_L(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in I/O, to an object pointed to by s1 located in program memory, with incrementing destination program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STREAMOUT_B

Prototype

void *STREAMOUT_B(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O.

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

None.

STREAMOUT_S

Prototype

void *STREAMOUT_S(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STREAMOUT_L

Prototype

void *STREAMOUT_L(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STREAMOUTI_B

Prototype

void *STREAMOUTI_B(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O, with incrementing source program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

None.

STREAMOUTI_S

Prototype

void *STREAMOUTI_S(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O, with incrementing source program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STREAMOUTI_L

Prototype

void *STREAMOUTI_L(void *s1, void *s2, long n);

Description

Function moves n bytes from an object pointed to by s2 located in program memory, to an object pointed to by s1 located in I/O, with incrementing source program memory address.

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STRCMP_B

Prototype

long *STRCMP_B(char *s1, char *s2);

Description

Function compares strings s1 and s2 and returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).
Accordingly, the result is greater than zero if s1 is greater than s2 and vice versa.

The behavior of the STRCMP_B instruction is exactly the same as the standard C strcmp() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).

Requires

Nothing.

Notes

None.

STRCMP_S

Prototype

void *STRCMP_S(char *s1, char *s2);

Description

Function compares strings s1 and s2 and returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).
Accordingly, the result is greater than zero if s1 is greater than s2 and vice versa.

The behavior of the STRCMP_B instruction is exactly the same as the standard C strcmp() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STRCMP_L

Prototype

void *STRCMP_L(char *s1, char *s2);

Description

Function compares strings s1 and s2 and returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).
Accordingly, the result is greater than zero if s1 is greater than s2 and vice versa.

The behavior of the STRCMP_B instruction is exactly the same as the standard C strcmp() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STPCPY_B

Prototype

char *STPCPY_B(char *s1, char *s2);

Description

Function copies the string s2 into the string s1. If copying is successful, the function returns pointer to s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the STPCPY_B instruction is exactly the same as the standard C stpcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Nothing.

Notes

None.

STPCPY_S

Prototype

char *STPCPY_S(char *s1, char *s2);

Description

Function copies the string s2 into the string s1. If copying is successful, the function returns pointer to s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the STPCPY_B instruction is exactly the same as the standard C stpcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STPCPY_L

Prototype

char *STPCPY_L(char *s1, char *s2);

Description

Function copies the string s2 into the string s1. If copying is successful, the function returns pointer to s1. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of the STPCPY_L instruction is exactly the same as the standard C stpcpy() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

The function returns address of the object pointed to by s1.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

STRLEN_B

Prototype

long *STRLEN_B(char *s);

Description

Function returns the length of the string s (the terminating null character does not count against string’s length).

The behavior of the STRLEN_B instruction is exactly the same as the standard C strlen() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

Function returns the length of the string.

Requires

Nothing.

Notes

None.

STRLEN_S

Prototype

long STRLEN_S(char *s);

Description

Function returns the length of the string s (the terminating null character does not count against string’s length).

The behavior of the STRLEN_S instruction is exactly the same as the standard C strlen() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

Function returns the length of the string.

Requires

Function parameters must have alignment 2.

Notes

Use this function when function parameters have alignment 2.

STRLEN_L

Prototype

long STRLEN_L(char *s);

Description

Function returns the length of the string s (the terminating null character does not count against string’s length).

The behavior of the STRLEN_L instruction is exactly the same as the standard C strlen() function in ISO/IEC 9899:1990 ("ISO C90").

Returns

Function returns the length of the string.

Requires

Function parameters must have alignment 4.

Notes

Use this function when function parameters have alignment 4.

Copyright (c) 2002-2015 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries? 
Find them on LibStock - A place for the code