Built-in Routines

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

The Lo, Hi, Higher, Highest routines are implemented as macros. If you want to use these functions you must include built_in.h header file (located in the include 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, 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]

Returns

Lowest 8 bits (byte) of param, bits 7..0.

Description

Function returns the lowest byte of param. 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.

Requires

None.

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

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

Hi

Prototype

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

Returns

Returns next to the lowest byte of param, bits 8..15.

Description

Function returns next to the lowest byte of param. 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.

Requires

None.

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

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

Higher

Prototype

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

Returns

Returns next to the highest byte of param, bits 16..23.

Description

Function returns next to the highest byte of param. 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.

Requires

None.

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

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

Highest

Prototype

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

Returns

Returns the highest byte of param, bits 24..31.

Description

Function returns the highest byte of param. 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.

Requires

None.

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

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

LoWord

Prototype

unsigned int LoWord(unsigned long number);

Description

The function returns low word of number. The function does not interpret bit patterns of number – 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
  • number: input number
Returns

Low word of number, 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 number);

Description

The function returns high word of number. The function does not interpret bit patterns of number – 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
  • number: input number
Returns

High word of number, bits 31..16.

Requires

Nothing.

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

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

None.

Delay_us

Prototype

void Delay_us(const unsigned long time_in_us);

Returns

Nothing.

Description

Creates a software delay in duration of time_in_us microseconds (a constant). Range of applicable constants depends on the oscillator frequency.

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. This routine generates nested loops using registers R13, R12, R11 and R10. The number of used registers varies from 0 to 4, depending on requested time_in_us.

Requires

Nothing.

Example
Delay_us(1000);  /* One millisecond pause */

Delay_ms

Prototype

void Delay_ms(const unsigned long time_in_ms);

Returns

Nothing.

Description

Creates a software delay in duration of time_in_ms milliseconds (a constant). Range of applicable constants depends on the oscillator frequency.

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. This routine generates nested loops using registers R13, R12, R11 and R10. The number of used registers varies from 0 to 4, depending on requested time_in_ms.

Requires

Nothing.

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

Vdelay_ms

Prototype

void Vdelay_ms(unsigned time_in_ms);

Returns

Nothing.

Description

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

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

Requires

Nothing.

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

VDelay_Advanced_ms

Prototype

void VDelay_Advanced_ms(unsigned time_in_ms, unsigned Current_Fosc_kHz);

Returns

Nothing.

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.

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

Requires

Nothing.

Example
pause = 1000;
fosc = 10000;

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

Delay_Cyc

Prototype

void Delay_Cyc(char Cycles_div_by_10);

Returns

Nothing.

Description

Creates a delay based on MCU clock. Delay lasts for 10 times the input parameter in MCU cycles.

Note that Delay_Cyc is library function rather than a built-in routine; it is presented in this topic for the sake of convenience. There are limitations for Cycles_div_by_10 value. Value Cycles_div_by_10 must be between 3 and 255.

Requires

Nothing.

Example
Delay_Cyc(10);  /* Hundred MCU cycles pause */

Clock_kHz

Prototype

unsigned Clock_kHz(void);

Returns

Device clock in kHz, rounded to the nearest integer.

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.

Requires

Nothing.

Example
clk = Clock_kHz();

Clock_MHz

Prototype

unsigned short Clock_MHz(void);

Returns

Device clock in MHz, rounded to the nearest integer.

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.

Requires

Nothing.

Example
clk = Clock_MHz();

Get_Fosc_kHz

Prototype

unsigned long Get_Fosc_kHz(void);

Returns

Device clock in kHz, rounded to the nearest integer.

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 convenience.

Requires

Nothing.

Example
clk = Get_Fosc_kHz();

Swap

Prototype

char swap(char input);

Returns

Swapped nibbles of the input byte.

Description

Function swaps nibbles of the input parameter.

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.

Requires

Nothing.

Example
char input, swapped_input;

input = 0xAF;
swapped_input = swap(input); // routine will return 0xFA i.e. swapped nibbles of the input parameter
Copyright (c) 2002-2012 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