GBDK 2020 Docs  4.2.0
API Documentation for GBDK 2020
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
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 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
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
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);
#define FAR_CALL(ptr, typ,...)
Definition: far_ptr.h:65
unsigned short int uint16_t
Definition: stdint.h:52
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
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 uint8_t __call_banked_bank
extern