Built-in Routines

The mikroC PRO for ARM 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 int x, unsigned int y);

Description

Creates a delay based on MCU clock. Delay lasts for x*16384 + y MCU clock cycles.

Parameters
  • x: NumberOfCycles divided by 16384
  • y: remainder of the NumberOfCycles/16384 division
Returns

Nothing.

Requires

Nothing.

Example
Delay_Cyc(1, 10);  /* 1x16384 + 10 = 16394 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_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.

SystemReset

Prototype

void SystemReset();

Description

This function will perform a software reset of the entire device. The processor and all peripherals are reset and all device registers will return to their default values
(with the exception of the reset cause register, which will maintain its current value but have the software reset bit set as well).

Parameters

None.

Returns

Nothing.

Requires

Nothing.

Example
SystemReset();
Notes

None.

CPU_REG_GET

Prototype

unsigned long CPU_REG_GET(const char reg);

Description

Function returns the value of the core register, based upon the argument entered.

Parameters

Parameter must be a constant from the enumerated built-in constants list, which can be found at the bottom of this page.

Returns

Value of the core register.

Requires

Nothing.

Example
unsigned long register_value ;

register_value = CPU_REG_GET(CPU_PRIMASK);
Notes

None.

CPU_REG_SET

Prototype

void CPU_REG_SET(const char reg, unsigned long value);

Description

Function sets the value of the core register, based upon the register argument.

Parameters
  • register: Register, must be a constant from the enumerated built-in constants list, which can be found at the bottom of this page.
  • value: Register value.
Returns

Nothing.

Requires

Nothing.

Example
CPU_REG_SET(CPU_PRIMASK);
Notes

None.

RestoreInterrupts

Prototype

void RestoreInterrupts(unsigned long primask);

Description

Restores (enables or disables) core interrupts based on the last PRIMASK register value given as a routine parametar.

Parameters

None.

Returns

Returns the value stored in the PRIMASK register before the interrupts were enabled/disabled.

Requires

Nothing.

Example
RestoreInterrupts(CPU_PRIMASK);
Notes

None.

EnableInterrupts

Prototype

unisgned long EnableInterrupts();

Description

This function enables the processor interrupt and allows the processor to respond to interrupts.
This does not affect the set of interrupts enabled in the interrupt controller; it just gates the single interrupt from the controller to the processor.

Parameters

None.

Returns

Returns the value stored in the PRIMASK register.

Requires

Nothing.

Example
status_value = EnableInterrupts();
Notes

None.

DisableInterrupts

Prototype

unsigned long DisableInterrupts();

Description

This function disables the processor interrupt and prevents the processor from receiving interrupts.
This does not affect the set of interrupts enabled in the interrupt controller; it just gates the single interrupt from the controller to the processor.

Parameters

Returns the value stored in the PRIMASK register.

Returns

Nothing.

Requires

Nothing.

Example
status_value = DisableInterrupts();
Notes

None.

NVIC_IntEnable

Prototype

void NVIC_IntEnable(const unsinged long ivt);

Description

This procedure enables an interrupt vector. The specified interrupt vector is enabled in the interrupt controller.
Other enables for the interrupt (such as at the peripheral level) are unaffected by this procedure.

Parameters
  • ivt: - specifies the interrupt vector to be enabled.
Returns

Nothing.

Requires

Nothing.

Example
NVIC_IntEnable(IVT_INT_TIMER0A);
Notes

The list of the available interrupt vectors be be seen in Code Assistant, by typing IVT and pressing Ctrl + Space,
or in the definition file of the MCU, which can be opened by pressing Ctrl + Alt + D.

NVIC_IntDisable

Prototype

void NVIC_IntDisable(const unsigned long ivt);

Description

This procedure disables an interrupt vector. The specified interrupt vector is disabled in the interrupt controller.
Other enables for the interrupt (such as at the peripheral level) are unaffected by this function.

Parameters
  • ivt: - specifies the interrupt vector to be enabled.
Returns

Nothing.

Requires

Nothing.

Example
NVIC_IntDisable(IVT_INT_TIMER0A);
Notes

The list of the available interrupt vectors be be seen in Code Assistant, by typing IVT and pressing Ctrl + Space,
or in the definition file of the MCU, which can be opened by pressing Ctrl + Alt + D.

Core Registers
CPU_APSR CPU_IAPSR CPU_EAPSR CPU_XPSR CPU_IPSR CPU_EPSR CPU_IEPSR
CPU_MSP CPU_PSP CPU_PRIMASK CPU_BASEPRI CPU_BASEPRI CPU_BASEPRI_MAX CPU_CONTROL
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