GBDK 2020 Docs 4.4.0 API Documentation for GBDK 2020

Data Structures | Macros | Typedefs | Functions | Variables
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);
FAR_CALL
#define FAR_CALL(ptr, typ,...)
Definition: far_ptr.h:65
uint16_t
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

  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