---
title: "Loader"
canonical_url: https://developer.repebble.com/pebbleos/docs/samples/subsys/loader/image/
last_updated: 2026-11-18
sdk_version: 4.44
---
# Loader

Source: https://developer.repebble.com/pebbleos/docs/samples/subsys/loader/image/

This sample loads a small image the way apps are loaded: the loader copies its stored part to RAM, clears the part after it that is not stored, and applies its relocations. Each relocation names a 32-bit slot that holds an offset into the image, and turns it into the address it now has.

The image is made in C here, a header, three pointer slots and two strings, with the relocation table after them. The loader refuses a relocation that would patch the header, and an image larger than the memory given to it.

Relocated pointers are 32 bits wide, so the sample does not run natively on 64-bit hosts.

Run:

`pbl samples samples/subsys/loader/image`

Boards:

every board but native\_emery, native\_flint, native\_gabbro

## Sources

src/main.c

```
#include \<errno.h\>#include \<stddef.h\>#include \<stdint.h\>#include \<stdio.h\>#include \<string.h\>#include \<pbl/loader/loader.h\>#define BSS\_SIZE 16U/\* \* An image as a linker would emit it: a header, pointer slots holding offsets into the image, \* the data they point to, then the relocation table listing the slots. Only the file part is \* copied; the zero-filled part after it is not stored. \*/struct image {char magic[4];uint32\_t version;uint32\_t greeting;uint32\_t farewell;uint32\_t counter;char strings[24];uint32\_t relocs[3];};#define FILE\_SIZE offsetof(struct image, relocs)static const struct image s\_image = {.magic = {'I', 'M', 'G', '0'},.version = 1,.greeting = offsetof(struct image, strings),.farewell = offsetof(struct image, strings) + 6,.counter = FILE\_SIZE,.strings = "Hello\0Goodbye",.relocs = {offsetof(struct image, greeting),offsetof(struct image, farewell),offsetof(struct image, counter),},};static const struct pbl\_loader\_image s\_layout = {.file\_size = FILE\_SIZE,.mem\_size = FILE\_SIZE + BSS\_SIZE,.header\_size = offsetof(struct image, greeting),.reloc\_offset = offsetof(struct image, relocs),.reloc\_count = 3,};/\* The source could be flash or a file; here it is a copy in the firmware. \*/static int prv\_read(void \*ctx, size\_t offset, void \*buf, size\_t len) {const uint8\_t \*src = ctx;if (offset \> sizeof(s\_image) || len \> sizeof(s\_image) - offset) {return -EINVAL;}memcpy(buf, &src[offset], len);return 0;}static uint32\_t s\_ram[32];static int prv\_load(const struct pbl\_loader\_image \*layout, const void \*image, void \*dst,size\_t dst\_size) {const struct pbl\_loader\_source src = {.read = prv\_read, .ctx = (void \*)image};int ret;ret = pbl\_loader\_copy(layout, &src, dst, dst\_size);if (ret \< 0) {return ret;}/\* Each slot gets the address of what it points to, now that the image has its place. \*/return pbl\_loader\_relocate(layout, &src, dst, dst\_size, nullptr, nullptr);}int main(void) {const struct image \*img = (const struct image \*)s\_ram;struct pbl\_loader\_image big = s\_layout;struct image bad = s\_image;int ret;ret = prv\_load(&s\_layout, &s\_image, s\_ram, sizeof(s\_ram));if (ret \< 0) {fprintf(stderr, "loader: load failed (%d)\n", ret);return ret;}printf("loader: image %.4s version %u, %u bytes stored, %u in memory\n", img-\>magic,(unsigned int)img-\>version, (unsigned int)s\_layout.file\_size,(unsigned int)s\_layout.mem\_size);printf("loader: greeting \"%s\", farewell \"%s\"\n", (const char \*)(uintptr\_t)img-\>greeting,(const char \*)(uintptr\_t)img-\>farewell);uint32\_t \*counter = (uint32\_t \*)(uintptr\_t)img-\>counter;printf("loader: counter in the zero-filled part: %s, starts at %u\n",(uint8\_t \*)counter == (uint8\_t \*)s\_ram + FILE\_SIZE ? "yes" : "no", (unsigned int)\*counter);/\* A relocation must not patch the header. \*/bad.relocs[0] = offsetof(struct image, version);printf("loader: relocation into the header: %s\n",prv\_load(&s\_layout, &bad, s\_ram, sizeof(s\_ram)) == -EINVAL ? "-EINVAL" : "loaded");big.mem\_size = sizeof(s\_ram) + 1U;printf("loader: image larger than its memory: %s\n",prv\_load(&big, &s\_image, s\_ram, sizeof(s\_ram)) == -ENOMEM ? "-ENOMEM" : "loaded");printf("Sample done\n");return 0;}
```

## Output

```
loader: image IMG0 version 1, 44 bytes stored, 60 in memory
loader: greeting "Hello", farewell "Goodbye"
loader: counter in the zero-filled part: yes, starts at 0
loader: relocation into the header: -EINVAL
loader: image larger than its memory: -ENOMEM
Sample done
```

Generated from PebbleOS [7753e801d](https://github.com/coredevices/pebbleos/commit/7753e801d93d20f2d37534ce2fa69d9952015237). This page is maintained in the pebbleos repository: [docs/samples/subsys/loader/image.md](https://github.com/coredevices/pebbleos/blob/7753e801d93d20f2d37534ce2fa69d9952015237/docs/samples/subsys/loader/image.md).
