Built-in Routines
mikroPascal PRO for PIC compiler provides a set of useful built-in utility functions. Built-in functions do not have any special requirements. You can use them in any part of 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
and Get_Fosc_kHz
are actual Pascal routines. Their sources can be found in Delays.mpas
file located in the Uses
folder of the compiler.
Lo
Prototype |
function Lo(number: longint): byte; |
---|---|
Returns |
Lowest 8 bits (byte)of |
Description |
Function returns the lowest byte of 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 |
Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). |
Example |
d := 0x12345678; tmp := Lo(d); // Equals 0x78 Lo(d) := 0xAA; // d equals 0x123456AA |
Hi
Prototype |
function Hi(number: longint): byte; |
---|---|
Returns |
Returns next to the lowest byte of |
Description |
Function returns next to the lowest byte of 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 |
Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). |
Example |
d := 0x12345678; tmp := Hi(d); // Equals 0x56 Hi(d) := 0xAA; // d equals 0x1234AA78 |
Higher
Prototype |
function Higher(number: longint): byte; |
---|---|
Returns |
Returns next to the highest byte of |
Description |
Function returns next to the highest byte of 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 |
Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). |
Example |
d := 0x12345678; tmp := Higher(d); // Equals 0x34 Higher(d) := 0xAA; // d equals 0x12AA5678 |
Highest
Prototype |
function Highest(number: longint): byte; |
---|---|
Returns |
Returns the highest byte of |
Description |
Function returns the highest byte of 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 |
Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). |
Example |
d := 0x12345678; tmp := Highest(d); // Equals 0x12 Highest(d) := 0xAA; // d equals 0xAA345678 |
LoWord
Prototype |
function LoWord(val : longint) : word; |
---|---|
Description |
The function returns low word of Parameters :
|
Parameters |
number
|
Returns |
Low word of |
Requires |
Nothing. |
Example |
d := 0x12345678; tmp := LoWord(d); // Equals 0x5678 LoWord(d) := 0xAAAA; // d equals 0x1234AAAA |
Notes |
None. |
HiWord
Prototype |
function HiWord(val : longint) : word; |
---|---|
Description |
The function returns high word of Parameters :
|
Parameters |
number
|
Returns |
High word of |
Requires |
Nothing. |
Example |
d := 0x12345678; tmp := HiWord(d); // Equals 0x1234 HiWord(d) := 0xAAAA; // d equals 0xAAAA5678 |
Notes |
None. |
Inc
Prototype |
procedure Inc(var par : longint); |
---|---|
Returns |
Nothing. |
Description |
Increases parameter |
Requires |
Nothing. |
Example |
p := 4; Inc(p); // p is now 5 |
Dec
Prototype |
procedure Dec(var par : longint); |
---|---|
Returns |
Nothing. |
Description |
Decreases parameter |
Requires |
Nothing. |
Example |
p := 4; Dec(p); // p is now 3 |
Chr
Prototype |
function Chr(code : byte) : char; |
---|---|
Returns |
Returns a character associated with the specified character |
Description |
Function returns a character associated with the specified character This is an “inline” routine; the code is generated in the place of the call. |
Requires |
Nothing. |
Example |
c := Chr(10); // returns the linefeed character |
Ord
Prototype |
function Ord(character : char) : byte; |
---|---|
Returns |
ASCII code of the |
Description |
Function returns ASCII code of the This is an “inline” routine; the code is generated in the place of the call. |
Requires |
Nothing. |
Example |
c := Ord('A'); // returns 65 |
SetBit
Prototype |
procedure SetBit(var register : byte; rbit : byte); |
---|---|
Returns |
Nothing. |
Description |
Function sets the bit 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 |
SetBit(PORTB, 2); // Set RB2 |
ClearBit
Prototype |
procedure ClearBit(var register : byte; rbit : byte); |
---|---|
Returns |
Nothing. |
Description |
Function clears the bit 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 |
ClearBit(PORTC, 7); // Clear RC7 |
TestBit
Prototype |
function TestBit(register, rbit : byte) : byte; |
---|---|
Returns |
If the bit is set, returns 1, otherwise returns 0. |
Description |
Function tests if the bit 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 |
flag := TestBit(PORTE, 2); // 1 if RE2 is set, otherwise 0 |
Delay_us
Prototype |
procedure Delay_us(time_in_us: const dword); |
---|---|
Returns |
Nothing. |
Description |
Creates a software delay in duration of 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 |
Delay_us(1000); // One millisecond pause |
Delay_ms
Prototype |
procedure Delay_ms(time_in_ms: const dword); |
---|---|
Returns |
Nothing. |
Description |
Creates a software delay in duration of 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 |
Delay_ms(1000); // One second pause |
Vdelay_ms
Prototype |
procedure Vdelay_ms(time_in_ms : word) |
---|---|
Returns |
Nothing. |
Description |
Creates a software delay in duration of Note that |
Requires |
Nothing. |
Example |
pause := 1000; Vdelay_ms(pause); // ~ one second pause |
VDelay_Advanced_ms
Prototype |
procedure VDelay_Advanced_ms(time_ms, Current_Fosc_kHz: word); |
---|---|
Returns |
Nothing. |
Description |
Creates a software delay in duration of Note that |
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 |
procedure Delay_Cyc(Cycles_div_by_10 : byte) |
---|---|
Returns |
Nothing. |
Description |
Creates a delay based on MCU clock. Delay lasts for 10 times the input parameter in MCU cycles. Note that |
Requires |
Nothing. |
Example |
Delay_Cyc(10); // Hundred MCU cycles pause |
Clock_kHz
Prototype |
function Clock_kHz(): word; |
---|---|
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 |
function Clock_MHz(): byte; |
---|---|
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 |
function Get_Fosc_kHz() : longint; |
---|---|
Returns |
Device clock in kHz. |
Description |
Function returns device clock in kHz, rounded to the nearest integer.
|
Requires |
Nothing. |
Example |
clk := Get_Fosc_kHz(); |
Swap
Prototype |
function Swap(arg : byte) : byte; |
---|---|
Returns |
Returns byte consisting of swapped nibbles. |
Description |
Swaps higher nibble (bits |
Requires |
Nothing. |
Example |
PORTB := 0xF0; PORTA := Swap(PORTB); // PORTA = PORTB = 0x0F |
Reset
Prototype |
procedure Reset(); |
---|---|
Returns |
Nothing. |
Description |
This procedure is equal to assembler instruction reset. This procedure works only for P18. |
Requires |
Nothing. |
Example |
Reset(); // Resets the MCU |
ClrWdt
Prototype |
procedure ClrWdt(); |
---|---|
Returns |
Nothing. |
Description |
This procedure is equal to assembler instruction |
Requires |
Nothing. |
Example |
ClrWdt(); // Clears WDT |
DisableContextSaving
Prototype |
procedure DisableContextSaving(); |
---|---|
Returns |
Nothing. |
Description |
Use the This exception can be overridden by placing an |
Requires |
This routine must be called from main. |
Example |
DisableContextSaving(); // instruct the compiler not to automatically perform context-switching |
SetFuncCall
Prototype |
procedure SetFuncCall(FuncName: string); |
---|---|
Returns |
Nothing. |
Description |
If the linker encounters an indirect function call (by a pointer to function), it assumes that any routine whose address was taken anywhere in the program can be called at that point if it's prototype matches the pointer declaration. Use the SetFuncCall directive within routine body to instruct the linker which routines can be called indirectly from that routine :
Routines specified in the Thus, placing |
Requires |
Nothing. |
Example: |
procedure first(p, q: byte); begin ... SetFuncCall(second); // let linker know that we will call the routine 'second' ... end |
SetOrg
Prototype |
procedure SetOrg(RoutineName: string; address: longint); |
---|---|
Returns |
Nothing. |
Description |
Use the |
Requires |
This routine must be called from main. |
Example |
SetOrg(UART1_Write, 0x1234); |
GetDateTime
Prototype |
function GetDateTime() : string; |
---|---|
Returns |
String with date and time when this routine is compiled. |
Description |
Use the |
Requires |
Nothing. |
Example |
str := GetDateTime(); |
DoGetDateTime
Prototype |
function DoGetDateTime() : string; |
---|---|
Returns |
String with date and time when this routine is compiled. |
Description |
Use the |
Requires |
Nothing. |
Example |
str := DoGetDateTime(); |
GetVersion
Prototype |
function GetVersion() : string; |
---|---|
Returns |
String with current compiler version. |
Description |
Use the |
Requires |
Nothing. |
Example |
str := GetVersion(); // for example, str will take the value of '8.2.1.6' |
DoGetVersion
Prototype |
function DoGetVersion() : string; |
---|---|
Returns |
String with current compiler version. |
Description |
Use the |
Requires |
Nothing. |
Example |
str := DoGetVersion(); // for example, str will take the value of '8.2.1.6' |
New
Prototype |
procedure New(var Ptr : pointer); |
---|---|
Description |
Allocates a block of memory from the memory Heap, taking care of the alignment. It is recommended to use this routine instead of GetMem. |
Parameters |
|
Returns |
Returns a pointer to the memory block allocated by the function; Otherwise 0 (no free blocks of memory are large enough). |
Requires |
Nothing. |
Notes |
None. |
Dispose
Prototype |
procedure Dispose(var Ptr : pointer); |
---|---|
Description |
Disposes a block of memory from the memory Heap, referenced by Ptr and returns its memory to the Heap. |
Parameters |
|
Returns | |
Requires |
Nothing. |
Notes |
After calling this routine, the value of Ptr is nil (0) (not assigned pointer). |
What do you think about this topic ? Send us feedback!