Payload API
The wiki is being retired!
Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
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.
This API is implemented by libpayload.
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.