Payload API

Payload API

This page discusses the API for passing parameters to new payloads and getting a return value back. In the description below, the term parent refers to the entity that is
starting the payload; nominally coreboot or a chooser payload. The term child or payload refers to the payload code that is being executed.

Passing Parameters

Parameters are passed from the parent to the child in the form of an array of zero terminated strings, similar to a standard C application.
The calling application pushes on the stack (in order): the the number of elements in the array (argc), a pointer to the array (argv and a magic number
(0x12345678).

After control has been passed to the payload, the stack will look like this:

Offset (from %esp)

Size

Parameter

Value

0x00

4

return address

0x04

4

Magic number

0x12345678

0x08

4

Pointer to the array (argv)

0x10

4

number of elements in the array (argc)

The payload should first check offset 0x04 for the magic number. If it is not present, then the payload should assume that the parent did not pass any parameters (probably because it was a legacy application). Failure to check for the magic number could result in mistaken values for argc and argv which could cause program failure.
After verifying the magic number, the payload can collect the other two elements and process them accordingly.

Return Value

After the payload has completed execution, i can return an integer exit code to the parent. The exit code will be passed in the %eax register. After
regaining control, the parent should take care to save off the value of %eax before using the register for other purposes.