millfork/docs/lang/functions.md

[< back to index](../index.md)

# Function definitions

Syntax:

`[segment (<segment>)] [<modifiers>] <return_type> <name> ( <params> ) [align ( <alignment> )] [@ <address>] { <body> }`

`[segment (<segment>)] [<modifiers>] <return_type> <name> ( <params> ) [align ( <alignment> )] [@ <address>] = <expression>`

`[segment (<segment>)] asm <return_type> <name> ( <params> ) @ <address> extern`

* `<segment>`: segment name; if absent, then defaults to `default_code_segment` as defined for the platform (usually `default`)

* `<modifiers>`: zero or more of the following:

    * `asm` – the function is written in assembly, not in Millfork (obligatory for `extern` functions), 
    see [Using 6502 assembly within Millfork programs#Assembly functions](./assembly.md#assembly-functions)
    or [Using 8080/LR35902/Z80 assembly within Millfork programs#Assembly functions](./assemblyz80.md#assembly-functions)
    
    * `macro` – the function is a macro, 
    see [Macros_and inlining#Macros](../abi/inlining.md#macros)
    
    * `inline` – the function should preferably be inlined
    see [Macros_and inlining#Inlining](../abi/inlining.md#automatic-inlining)
    
    * `noinline` – the function should never be inlined
    
    * `interrupt` – the function is a hardware interrupt handler.
    You are not allowed to call such functions directly.
    The function cannot have parameters and the return type should be `void`.
    
    * `kernal_interrupt` – the function is an interrupt handler called from a generic vendor-provider hardware interrupt handler.
    The hardware instruction handler is assumed to have preserved the CPU registers,
    so this function only has to preserve the zeropage pseudoregisters.
    An example is the Commodore 64 interrupt handler that calls the function at an address read from $314/$315.
    Unlike hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions. 
    
* `<return_type>` is a valid return type, see [Types](./types.md)

* `<params>` is a comma-separated list of parameters, in form `type name`. Allowed types are the same as for local variables.

* `<alignment>` is either a numeric literal that is a power of 2, or keyword `fast`.
    The function will be allocated at the address divisible by alignment.
    `fast` means different things depending on the target platform:

    * on 6502, it means that the function will not cross a page boundary
    * on Z80, it is ignored   

* `<address>` is a constant expression that defines where in the memory the function is or will be located.

* `extern` is a keyword than marks functions that are not defined in the current program, 
but are likely to be available at certain address in memory. 
Such functions should be marked as written in assembly and should have their parameters passed through registers.

* `<body>` is a newline-separated list of either Millfork or assembly statements

* `<expression>` is an expression. It is equivalent to a function body of form `{ return <expression> }`.
-												Documentation improvements

											
										
										
											2018-04-02 22:21:26 +00:00
+								[< back to index](../index.md)
-												Some more documentation

											
										
										
											2018-01-04 00:15:04 +00:00
+								# Function definitions
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
+								Syntax:
-												Add align keyword

											
										
										
											2018-10-04 19:33:10 +00:00
+								`[segment (<segment>)] [<modifiers>] <return_type> <name> ( <params> ) [align ( <alignment> )] [@ <address>] { <body> }`
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
-												Short syntax for small functions

											
										
										
											2019-04-15 17:56:14 +00:00
+								`[segment (<segment>)] [<modifiers>] <return_type> <name> ( <params> ) [align ( <alignment> )] [@ <address>] = <expression>`
-												Preliminary segment support; C16/+4 fixes

											
										
										
											2018-03-15 22:09:19 +00:00
+								`[segment (<segment>)] asm <return_type> <name> ( <params> ) @ <address> extern`
-												Add docs about Intel asm syntax

											
										
										
											2018-08-03 15:26:26 +00:00
+								* `<segment>`: segment name; if absent, then defaults to `default_code_segment` as defined for the platform (usually `default`)
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
 								* `<modifiers>`: zero or more of the following:
-												Use zero page locations as as pseudo-registers; 8-bit multiplication and 16-bit shifts

											
										
										
											2018-03-05 11:05:37 +00:00
+								    * `asm` – the function is written in assembly, not in Millfork (obligatory for `extern` functions),
-												Add docs about Intel asm syntax

											
										
										
											2018-08-03 15:26:26 +00:00
+								    see [Using 6502 assembly within Millfork programs#Assembly functions](./assembly.md#assembly-functions)
 								    or [Using 8080/LR35902/Z80 assembly within Millfork programs#Assembly functions](./assemblyz80.md#assembly-functions)
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
-												Tons of things:
– changed `inline` to `macro`
– added support for parameters for macros written in Millfork
– added `inline`, `noinline`, `register` hints
– added <<<< operator
– pointer dereference expressions are now supported more widely
– C64 library fixes
– added `-O1` command line option as an alias for `-O`

											
										
										
											2018-02-01 21:39:38 +00:00
+								    * `macro` – the function is a macro,
 								    see [Macros_and inlining#Macros](../abi/inlining.md#macros)
-												Use zero page locations as as pseudo-registers; 8-bit multiplication and 16-bit shifts

											
										
										
											2018-03-05 11:05:37 +00:00
+								    * `inline` – the function should preferably be inlined
-												Minor documentation updates

											
										
										
											2018-07-30 22:58:43 +00:00
+								    see [Macros_and inlining#Inlining](../abi/inlining.md#automatic-inlining)
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
-												Use zero page locations as as pseudo-registers; 8-bit multiplication and 16-bit shifts

											
										
										
											2018-03-05 11:05:37 +00:00
+								    * `noinline` – the function should never be inlined
 								    * `interrupt` – the function is a hardware interrupt handler.
 								    You are not allowed to call such functions directly.
-												Documentation updates

											
										
										
											2018-06-04 14:24:18 +00:00
+								    The function cannot have parameters and the return type should be `void`.
-												Use zero page locations as as pseudo-registers; 8-bit multiplication and 16-bit shifts

											
										
										
											2018-03-05 11:05:37 +00:00
 								    * `kernal_interrupt` – the function is an interrupt handler called from a generic vendor-provider hardware interrupt handler.
 								    The hardware instruction handler is assumed to have preserved the CPU registers,
 								    so this function only has to preserve the zeropage pseudoregisters.
 								    An example is the Commodore 64 interrupt handler that calls the function at an address read from $314/$315.
-												Documentation updates

											
										
										
											2018-06-04 14:24:18 +00:00
+								    Unlike hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions.
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
 								* `<return_type>` is a valid return type, see [Types](./types.md)
 								* `<params>` is a comma-separated list of parameters, in form `type name`. Allowed types are the same as for local variables.
-												Add align keyword

											
										
										
											2018-10-04 19:33:10 +00:00
+								* `<alignment>` is either a numeric literal that is a power of 2, or keyword `fast`.
 								    The function will be allocated at the address divisible by alignment.
 								    `fast` means different things depending on the target platform:
 								    * on 6502, it means that the function will not cross a page boundary
 								    * on Z80, it is ignored
-												Some syntax documentation

											
										
										
											2018-01-18 21:35:25 +00:00
+								* `<address>` is a constant expression that defines where in the memory the function is or will be located.
 								* `extern` is a keyword than marks functions that are not defined in the current program,
 								but are likely to be available at certain address in memory.
 								Such functions should be marked as written in assembly and should have their parameters passed through registers.
 								* `<body>` is a newline-separated list of either Millfork or assembly statements
-												Short syntax for small functions

											
										
										
											2019-04-15 17:56:14 +00:00
+								* `<expression>` is an expression. It is equivalent to a function body of form `{ return <expression> }`.