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.
Allocate ten
u16s, fill them with the squares of 0 to 9, and print them. What happens with the square of 300?Write a function that copies
nitems from one pointer to another, and test it underzeno runwith annthat is too big.In
driver.zeno, find eachunsafeblock and say what could go wrong in it.Take a pointer one item on with
+ 1andfreeit. Read the message.