Difference between revisions of "LAR Design"

From coreboot
Jump to: navigation, search
(Discussion)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
<div style="margin:0.5em 0; padding:0.5em; background:#ffd0d0; border:1px solid #aabbcc;">
 +
Please note that LAR is not used in coreboot v2 trunk (which has the alternative [[CBFS]]), but LAR is still used for coreboot v3.
 +
</div>
 +
 
= Introduction =
 
= Introduction =
  
LAR is the LinuxBIOS Archiver. It is a small utility that we use to create and change LinuxBIOS images and their modules.
+
<div style="margin:0.5em 0; padding:0.5em; background:#ffd0d0; border:1px solid #aabbcc;">
 +
Please note that this page is incomplete and outdated, the LAR documentation in the coreboot v3 source tree (including code comments) lists the current features and has up-to-date design documentation.
 +
</div>
 +
LAR is the coreboot archiver. It is a small utility that we use to create and change coreboot images and their modules.
  
 
It is a simple archiver, similar to cpio, ar or tar.
 
It is a simple archiver, similar to cpio, ar or tar.
Line 12: Line 19:
 
For a usage example see example.c.
 
For a usage example see example.c.
  
For questions contact Stefan Reinauer <stepan@coresystems.de>.
+
For questions contact [mailto:stepan@coresystems.de Stefan Reinauer].
 
+
  
 
= Usage =
 
= Usage =
Line 46: Line 52:
 
Headers have to be 16 byte aligned.
 
Headers have to be 16 byte aligned.
  
Headers have to be 16 byte aligned.
+
Data blocks have to be 16 byte aligned.
  
 
  |----------------------------|
 
  |----------------------------|
 
  | magic (8 bytes)            |
 
  | magic (8 bytes)            |
 
  |----------------------------|
 
  |----------------------------|
  | length (4 bytes)           |
+
  | compressed length (4 bytes)|
 +
|----------------------------|
 +
| real length (4 bytes)      |
 
  |----------------------------|
 
  |----------------------------|
 
  | checksum (4 bytes)        |
 
  | checksum (4 bytes)        |
 +
|----------------------------|
 +
| chksum compressed blob (4b)|
 
  |----------------------------|
 
  |----------------------------|
 
  | offset to blob (4 bytes)  |
 
  | offset to blob (4 bytes)  |
 
  |----------------------------|
 
  |----------------------------|
  | "path name"                | <-- null terminated, aligned to 16 bytes
+
  | compression id (4 bytes)  |
 +
|----------------------------|
 +
| "path",\0 (16b aligned)    |
 
  |----------------------------|
 
  |----------------------------|
 
  | blob (aligned to 16 bytes) |
 
  | blob (aligned to 16 bytes) |
 
  |----------------------------|
 
  |----------------------------|
  
 +
* compressed length means: length of blob
 +
* real length means: size of the uncompressed blob
 +
* checksum covers: header and blob, with "checksum" and "checksum compressed blob" set to 0
 +
* checksum compressed blob covers: the uncompressed data (no headers)
  
 
= TODO =
 
= TODO =
Line 82: Line 98:
  
 
Example:
 
Example:
* normal/initram=../../build/linuxbios.initram * none
+
* normal/initram=../../build/coreboot.initram * none
means: the file "normal/initram" inside the lar file will be created from "../../build/linuxbios.initram", with "none" compression. size isn't given and taken from the existing file
+
means: the file "normal/initram" inside the lar file will be created from "../../build/coreboot.initram", with "none" compression. size isn't given and taken from the existing file
  
 
Some syntax examples
 
Some syntax examples
  
  $ lar x linuxbios.rom # create linuxbios/* and linuxbios/MANIFEST
+
  $ lar x coreboot.rom # create coreboot/* and coreboot/MANIFEST
  
  $ lar c linuxbios.rom linuxbios/ # looks for linuxbios/MANIFEST
+
  $ lar c coreboot.rom coreboot/ # looks for coreboot/MANIFEST
  
  $ lar x linuxbios.rom # image without payload
+
  $ lar x coreboot.rom # image without payload
 
  $ cp payload.bin
 
  $ cp payload.bin
  $ lar c linuxbios.rom linuxbios/ -s 512K
+
  $ lar c coreboot.rom coreboot/ -s 512K
 
  $ # creates image, overiding size to 512K
 
  $ # creates image, overiding size to 512K

Latest revision as of 21:13, 7 November 2009

Please note that LAR is not used in coreboot v2 trunk (which has the alternative CBFS), but LAR is still used for coreboot v3.

Introduction

Please note that this page is incomplete and outdated, the LAR documentation in the coreboot v3 source tree (including code comments) lists the current features and has up-to-date design documentation.

LAR is the coreboot archiver. It is a small utility that we use to create and change coreboot images and their modules.

It is a simple archiver, similar to cpio, ar or tar.

Design goals were

 - minimum overhead
 - maximum fault tolerance
 - simplicity

For a usage example see example.c.

For questions contact Stefan Reinauer.

Usage

Create archive archive.lar containing files file1 ... fileN:

 $ lar c archive.lar file1 ... fileN

Extract files from archive.lar:

 $ lar x archive.lar [file1 ... fileN]

List files in archive:

 $ lar l archive.lar

Archive format

The rough format is:

|--------------|
| header       |
|--------------|
| data         |
|--------------|
| header       |
|--------------|
| data         |
|--------------|
 ...

Headers have to be 16 byte aligned.

Data blocks have to be 16 byte aligned.

|----------------------------|
| magic (8 bytes)            |
|----------------------------|
| compressed length (4 bytes)|
|----------------------------|
| real length (4 bytes)      |
|----------------------------|
| checksum (4 bytes)         |
|----------------------------|
| chksum compressed blob (4b)|
|----------------------------|
| offset to blob (4 bytes)   |
|----------------------------|
| compression id (4 bytes)   |
|----------------------------|
| "path",\0 (16b aligned)    |
|----------------------------|
| blob (aligned to 16 bytes) |
|----------------------------|
  • compressed length means: length of blob
  • real length means: size of the uncompressed blob
  • checksum covers: header and blob, with "checksum" and "checksum compressed blob" set to 0
  • checksum compressed blob covers: the uncompressed data (no headers)

TODO

  • Reading flash layouts
  • This does not enforce any alignment yet
  • Alignment enforcing will be optional

Discussion

Patrick Georgi and Stefan Reinauer discussed extending LAR so that it handles a MANIFEST file.

This file will list all existing files, and their current compression. If a file is in the MANIFEST, it's compression status will not be changed. This feature is required for making sure that initram is not compressed.

MANIFEST will describe

  • compression of files
  • size of the unpacked image (optional on parse-time, to make it easier for "lar c" users)
  • bootblock name
  • other metadata?

Example:

  • normal/initram=../../build/coreboot.initram * none

means: the file "normal/initram" inside the lar file will be created from "../../build/coreboot.initram", with "none" compression. size isn't given and taken from the existing file

Some syntax examples

$ lar x coreboot.rom # create coreboot/* and coreboot/MANIFEST
$ lar c coreboot.rom coreboot/ # looks for coreboot/MANIFEST
$ lar x coreboot.rom # image without payload
$ cp payload.bin
$ lar c coreboot.rom coreboot/ -s 512K
$ # creates image, overiding size to 512K