The Zeno Book Zeno 0.1 zeno-lang.org

33 Unsafe Code

Zeno looks after memory in two ways: a collector, or one owner for every value. This chapter is about the third way, the one C has: ask for memory, use it through a pointer, and give it back yourself. It is for the places where firmware must control every byte, such as a buffer that a peripheral fills, and it lives inside unsafe { }, a block that marks the lines Zeno cannot check.

33.1 The block

let bytes = allocate(u8, 16)

unsafe {
    bytes[0] = 0x41
    bytes[1] = u8(bytes[0] + 1)
    print(bytes[0], bytes[1])
    free(bytes)
}
65 66

unsafe { } is a block like the body of an if. Inside it, and only there, a program may do five things:

Inside unsafe only Why Zeno cannot check it
read through a pointer, p[i] a pointer does not know how long its memory is, or whether it was freed
write through a pointer, p[i] = v the same, and a wrong write damages something else
free(p) nothing says whether p is still used somewhere
read a register, r.read() the address is taken on trust, and reading can change the hardware
write a register, r.write(v) the same

Outside the block, the checker says so, and why:

let bytes = allocate(u8, 16)
print(bytes[0])
error: reading through a pointer goes inside `unsafe { }`. Zeno cannot check that it is right, so the block marks the lines where a mistake can damage memory
 --> main.zeno:2:7
  |
2 | print(bytes[0])
  |       ^

1 error found. Nothing was run.

The block does not turn anything off. Types are still checked inside it, numbers still report overflow, and lists are still looked after. It only allows those five things. So when a program damages memory, the lines to read are the ones inside the blocks, and grep unsafe finds them all.

Rust showed that a language can be safe by default and still let a driver do what drivers do, if the unsafe lines are marked and few. The mark is a block and not a word on a function, so it can be as small as one line. It gives no value, so let x = unsafe { p[0] } is refused: the block means one thing, "these lines are trusted".

33.2 Pointers

A pointer’s type says what one item is: pointer[u8] points at bytes. The item is a number of one size: u8 or i8 (1 byte), u16 or i16 (2), u32 or i32 (4), or int or float (8).

allocate(u8, 16) takes the item first and then how many, and gives a pointer[u8] to sixteen bytes that are all zero. p[i] is item i, counted from 0. p + 1 is the address of the next item, not the next byte, as in C. free(p) gives the memory back, and wants the pointer that allocate gave, not one worked out from it.

Everything else about a pointer is safe, and needs no block:

let bytes = allocate(u8, 16)
let second = bytes + 1
print(second - 1 == bytes, bytes)
let all = [bytes, second]
unsafe {
    free(bytes)
}
true <pointer[u8]>

An address that points nowhere is harmless until somebody reads or writes through it.

33.3 What zeno run catches

A compiled program holds an address and nothing more, as a C program does. zeno run holds more: behind each pointer it keeps the block, its length, and whether it was freed. So it catches the four classic mistakes at the line that makes them, and says what a compiled program would have done instead:

let a = allocate(u8, 16)
let b = allocate(u8, 16)
unsafe {
    a[24] = 7
    print(b[0])
}
error: this writes over item 24 of a block that has 16 (0 to 15). `zeno run` checks every use of a pointer. A compiled program does not: it writes over whatever is beside the block
 --> main.zeno:4:5
  |
4 |     a[24] = 7
  |     ^
let a = allocate(u8, 4)
unsafe {
    free(a)
    print(a[0])
}
error: this reads memory that was freed. `zeno run` checks every use of a pointer. A compiled program does not: it reads whatever is there now, which may be somebody else's
 --> main.zeno:4:11
  |
4 |     print(a[0])
  |           ^
let a = allocate(u8, 4)
unsafe {
    free(a)
    free(a)
}
error: this memory was freed already. `zeno run` checks every `free`. A compiled program does not: freeing twice damages the memory it hands out next
 --> main.zeno:4:5
  |
4 |     free(a)
  |     ^

Built with --no-collector, the first program runs to its end and prints 7: in the pool, b lies just after a, so item 24 of a is item 0 of b. Nothing went wrong that the machine could see. That is the whole danger, and the reason to run a program under zeno run first.

33.4 Registers

A register (The Board) is made with its size and address, register(u32, 0x4000_4400), and its type is Register[u32]. Making one and passing it around is safe; read() and write(v) go inside the block. On a real board a write is one line of C through a volatile pointer, which tells the C compiler that somebody else is watching this memory: it may not skip the access, repeat it or move it.

33.5 A driver

This program from the examples folder is a driver for a made-up serial port. Bytes wait in a queue whose memory the program asks for and gives back by hand, and go out through three registers. Each line that Zeno cannot check is inside unsafe:

examples/driver.zeno

# driver.zeno: memory by hand and registers, the way a C driver does it.
#
#     zeno run examples/driver.zeno          every use of a pointer is checked
#     zeno build --memory examples/driver.zeno && ./driver
#     zeno build --no-collector --memory examples/driver.zeno && ./driver
#
# A driver for a made-up serial port. Bytes wait in a queue whose memory
# the program asks for and gives back itself, and they go out through
# three registers at fixed addresses.
#
# Zeno cannot check a line that reads or writes through a pointer, frees
# one, or touches a register. Each such line is inside `unsafe { }`, so
# those are the blocks to read twice. docs/unsafe.md walks through it.

from board import register

# The port's registers, at the addresses its data sheet would give.
let control = register(u32, 0x4000_4400)    # bit 0 turns the port on, bit 3 the sender
let divider = register(u16, 0x4000_4408)    # clock ticks for each bit
let data = register(u8, 0x4000_440C)        # a byte written here is sent

let PORT_ON = 1 << 0
let SENDER_ON = 1 << 3

# Bytes that wait to be sent: first in, first out.
class Queue {
    bytes: pointer[u8]    # `size` bytes, asked for with `allocate`
    size: int
    first: int            # where the oldest byte is
    count: int            # how many are waiting

    # Add a byte at the end. `false` when there is no room.
    function put(self, byte: u8) -> bool {
        if self.count == self.size {
            return false
        }
        let at = (self.first + self.count) % self.size
        unsafe { self.bytes[at] = byte }
        self.count += 1
        return true
    }

    # Take the oldest byte out. `none` when nothing waits.
    function get(self) -> u8 or none {
        if self.count == 0 {
            return none
        }
        let at = self.first
        self.first = (self.first + 1) % self.size
        self.count -= 1
        unsafe { return self.bytes[at] }
    }

    # Give the memory back. The queue must not be used after this.
    function close(self) {
        unsafe { free(self.bytes) }
        self.size = 0
        self.count = 0
    }
}

function open_queue(size: int) -> Queue {
    return Queue(allocate(u8, size), size, 0, 0)
}

# Turn the port on, keeping every other bit of `control` as it was.
function start(ticks: u16) {
    unsafe {
        divider.write(ticks)
        control.write(u32(control.read() | PORT_ON | SENDER_ON))
    }
}

function stop() {
    unsafe {
        control.write(u32(control.read() & ~(PORT_ON | SENDER_ON)))
    }
}

# Send everything that waits. The answer is how many bytes went out.
function flush(queue: Queue) -> int {
    var sent = 0
    while true {
        let byte = queue.get()
        if byte is none {
            return sent
        }
        unsafe { data.write(byte) }
        sent += 1
    }
    return sent
}

# The sum of `count` bytes from `bytes` on, kept to eight bits.
function checksum(bytes: pointer[u8], count: int) -> u8 {
    var sum = 0
    unsafe {
        for i in range(count) {
            sum = (sum + bytes[i]) & 0xFF
        }
    }
    return u8(sum)
}

let queue = open_queue(4)
start(104)

# Six bytes into a queue of four: the last two do not fit.
var refused = 0
for byte in [0x5A, 0x65, 0x6E, 0x6F, 0x21, 0x0A] {
    if not queue.put(u8(byte)) {
        refused += 1
    }
}
print("waiting:", queue.count, "refused:", refused)

# `queue.bytes + 1` is the same memory, one byte further on. Working out
# an address is safe. Only reading through it is not.
print("checksum of all four:", checksum(queue.bytes, 4))
print("checksum of the last three:", checksum(queue.bytes + 1, 3))

print("sent:", flush(queue))

# The queue goes round: two more bytes land where the first two were.
queue.put(0x21)
queue.put(0x0A)
print("sent:", flush(queue))

stop()
queue.close()
print(control, data, queue.bytes)
register 0x40004408 = 0x0068
register 0x40004400 = 0x00000009
waiting: 4 refused: 2
checksum of all four: 156
checksum of the last three: 66
register 0x4000440c = 0x5a
register 0x4000440c = 0x65
register 0x4000440c = 0x6e
register 0x4000440c = 0x6f
sent: 4
register 0x4000440c = 0x21
register 0x4000440c = 0x0a
sent: 2
register 0x40004400 = 0x00000000
Register(0x40004400) Register(0x4000440c) <pointer[u8]>

zeno run, the VM, and every kind of compiled build print these same lines.

33.6 Memory by hand, and the other two

Memory from allocate is apart from the collector and from ownership: the collector never looks at it, and no block’s end frees it. In a build with no collector it comes from the pool, like everything else. A list, in the same program, is still looked after for you. Only what was asked for with allocate is yours to free.

allocate(T, n) gives a pointer[T] to n zeroed items, and free(p) gives it back. Reading and writing through a pointer, free, and reading and writing a register go inside unsafe { }, which allows those and changes nothing else. Working out, comparing and keeping addresses is safe. zeno run catches out-of-bounds use, use after free, double frees and freeing a moved pointer; a compiled program does not.

  1. Allocate ten u16s, fill them with the squares of 0 to 9, and print them. What happens with the square of 300?

  2. Write a function that copies n items from one pointer to another, and test it under zeno run with an n that is too big.

  3. In driver.zeno, find each unsafe block and say what could go wrong in it.

  4. Take a pointer one item on with + 1 and free it. Read the message.