far_ptr.h File Reference

#include <types.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
union	__far_ptr

Macros
#define	TO_FAR_PTR(ofs, seg)   (((FAR_PTR)seg << 16) | (FAR_PTR)ofs)
#define	FAR_SEG(ptr)   (((union __far_ptr *)&ptr)->segofs.seg)
#define	FAR_OFS(ptr)   (((union __far_ptr *)&ptr)->segofs.ofs)
#define	FAR_FUNC(ptr, typ)   ((typ)(((union __far_ptr *)&ptr)->segfn.fn))
#define	FAR_CALL(ptr, typ, ...)   (__call_banked_ptr=ptr,((typ)(&__call__banked))(__VA_ARGS__))

Typedefs
typedef uint32_t	FAR_PTR

Functions
void	__call__banked (void)
uint32_t	to_far_ptr (void *ofs, uint16_t seg)

Variables
volatile FAR_PTR	__call_banked_ptr
volatile void *	__call_banked_addr
volatile uint8_t	__call_banked_bank

Detailed Description

Far pointers include a segment (bank) selector so they are able to point to addresses (functions or data) outside of the current bank (unlike normal pointers which are not bank-aware).

See the banks_farptr example project included with gbdk.

Todo:

Add link to a discussion about banking (such as, how to assign code and variables to banks)

Macro Definition Documentation

TO_FAR_PTR

#define TO_FAR_PTR	(		ofs,
			seg
	)		(((FAR_PTR)seg << 16) | (FAR_PTR)ofs)

Macro to obtain a far pointer at compile-time

Parameters

ofs	Memory address within the given Segment (Bank)
seg	Segment (Bank) number

Returns

A far pointer (type FAR_PTR)

FAR_SEG

#define FAR_SEG

(

ptr

)

(((union __far_ptr *)&ptr)->segofs.seg)

Macro to get the Segment (Bank) number of a far pointer

Parameters

ptr	A far pointer (type FAR_PTR)

Returns

Segment (Bank) of the far pointer (type uint16_t)

FAR_OFS

#define FAR_OFS

(

ptr

)

(((union __far_ptr *)&ptr)->segofs.ofs)

Macro to get the Offset (address) of a far pointer

Parameters

ptr	A far pointer (type FAR_PTR)

Returns

Offset (address) of the far pointer (type void *)

FAR_FUNC

#define FAR_FUNC	(		ptr,
			typ
	)		((typ)(((union __far_ptr *)&ptr)->segfn.fn))

FAR_CALL

#define FAR_CALL	(		ptr,
			typ,
			...
	)		(__call_banked_ptr=ptr,((typ)(&__call__banked))(__VA_ARGS__))

Macro to call a function at far pointer ptr of type typ

Parameters

ptr	Far pointer of a function to call (type FAR_PTR)
typ	Type to cast the function far pointer to.
...	VA Args list of parameters for the function

type should match the definition of the function being called. For example:

// A function in bank 2
#pragma bank 2
uint16_t some_function(uint16_t param1, uint16_t param2) __banked {  return 1; };
 
...
// Code elsewhere, such as unbanked main()
// This type declaration should match the above function
typedef uint16_t (*some_function_t)(uint16_t, uint16_t) __banked;
 
// Using FAR_CALL() with the above as *ptr*, *typ*, and two parameters.
result = FAR_CALL(some_function, some_function_t, 100, 50);

Returns

Value returned by the function (if present)

Typedef Documentation

FAR_PTR

typedef uint32_t FAR_PTR

Type for storing a FAR_PTR

Function Documentation

__call__banked()

void __call__banked

(

void

)

to_far_ptr()

uint32_t to_far_ptr	(	void *	ofs,
		uint16_t	seg
	)

Obtain a far pointer at runtime

Parameters

ofs	Memory address within the given Segment (Bank)
seg	Segment (Bank) number

Returns

A far pointer (type FAR_PTR)

Variable Documentation

__call_banked_ptr

volatile FAR_PTR __call_banked_ptr

extern

__call_banked_addr

volatile void* __call_banked_addr

extern

__call_banked_bank

volatile uint8_t __call_banked_bank

extern