GBDK 2020 Docs
API Documentation for GBDK 2020
far_ptr.h File Reference

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 unsigned long FAR_PTR
 

Functions

void __call__banked ()
 
long to_far_ptr (void *ofs, int seg)
 

Variables

volatile FAR_PTR __call_banked_ptr
 
volatile void * __call_banked_addr
 
volatile unsigned char __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
ofsMemory address within the given Segment (Bank)
segSegment (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
ptrA far pointer (type FAR_PTR)
Returns
Segment (Bank) of the far pointer (type unsigned int)

◆ FAR_OFS

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

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

Parameters
ptrA 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
ptrFar pointer of a function to call (type FAR_PTR)
typType 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
int some_function(int param1, int param2) __banked { return 1; };
...
// Code elsewhere, such as unbanked main()
// This type declaration should match the above function
typedef int (*some_function_t)(int, int) __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 unsigned long FAR_PTR

Type for storing a FAR_PTR

Function Documentation

◆ __call__banked()

void __call__banked ( )

◆ to_far_ptr()

long to_far_ptr ( void *  ofs,
int  seg 
)

Obtain a far pointer at runtime

Parameters
ofsMemory address within the given Segment (Bank)
segSegment (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 unsigned char __call_banked_bank
extern
FAR_CALL
#define FAR_CALL(ptr, typ,...)
Definition: far_ptr.h:62