\input texinfo   @c -*- texinfo -*-
@c BEEBS Manual configuration file.
@c
@c Copyright (C) 2014 Embecosm Limited
@c Copyright (C) 2014 University of Bristol
@c
@c Contributor Jeremy Bennett <jeremy.bennett@embecosm.com>
@c Contributor James Pallister <james.pallister@bristol.ac.uk>
@c
@c This file is part of BEEBS
@c
@c This program is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the Free
@c Software Foundation; either version 3 of the License, or (at your option)
@c any later version.
@c
@c This program is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
@c more details.
@c
@c You should have received a copy of the GNU General Public License along
@c with this program.  If not, see <http://www.gnu.org/licenses/>.
@c

@setfilename beebs.info
@afourpaper
@include version.texi
@include config.texi
@dircategory Embedded development
@direntry
* @value{BEEBS}: The Bristol/Embecosm Embedded Benchmark Suite
@end direntry

@copying
This file documents the Bristol/Embecosm Embedded Benchmark Suite,
@value{BEEBS}.

Copyright @copyright{} 2014 Embecosm Limited.
Copyright @copyright{} 2014 University of Bristol.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

@setchapternewpage on
@settitle The @value{BEEBS} User Guide

@syncodeindex fn cp
@syncodeindex vr cp

@titlepage
@title The Bristol/Embecosm Embedded@inlinefmt{tex,@*} Benchmark Suite
@subtitle User Guide
@author Jeremy Bennett
@author Embecosm Limited
@author Issue 1 for beebs @value{VERSION}

@page
@vskip 0pt plus 1filll
@insertcopying

Published by Embecosm Limited and University of Bristol
@end titlepage

@contents

@node Top
@c Perhaps this should be the title of the document (but only for info,
@c not for TeX).  Existing GNU manuals seem inconsistent on this point.
@top Scope of this Document

This document is the user guide for @value{BEEBS}, the
Bristol/Embecosm Embedded Benchmark Suite.

@menu
* About::
* Building and Running @value{BEEBS}::
* Adding a New Board to @value{BEEBS}::
* Adding a New Benchmark to @value{BEEBS}::

* GNU Free Documentation License::  The license for this documentation
* Index::
@end menu

@node About
@chapter About @value{BEEBS}

@value{BEEBS} is a collection of free and open source benchmarks
suitable for use with deeply embedded systems. It is particularly
designed to aid in benchmarking energy consumption.

@node Building and Running @value{BEEBS}
@chapter Building and Running @value{BEEBS}

Building follows standard GNU protocols.

@menu
* Preparation::
* Configuring the Build::
* Building::
* Running::
* Known Issues::
@end menu

@node Preparation
@section Preparation

Unpack the software and create a @emph{separate} directory in which to
build it:

@example
@kbd{tar jxf beebs-@value{VERSION}.tar.bz2}
@kbd{mkdir bd}
@kbd{cd bd}
@end example

@node Configuring the Build
@section Configuring the Build
@cindex configuring @value{BEEBS}

Configure the software using the @command{configure} script in the
main directory.

There several options available, most of which are standard to GNU
@command{configure} scripts. Use @kbd{configure --help} to see all the options.
The most useful is @code{--host} to specify the host triple for the board on
which the test will be run.  @code{--prefix} can be used to specify an
installation location, although generally only the documentation is ever
installed.

There are two configuration options, which are specific to
@value{BEEBS}.

@table @code
@item --with-board=@var{boardname}
@cindex @code{--with-board}
Specifies the board on which the tests will be run.

@item --with-chip=@var{dir}
@cindex @code{--with-chip}
Specifies the particular chip used with the tests.

@end table

The board and chip names should match those of board or chip subdirectories
within the config folder of the source tree, and the chip name should be the
appropriate one for the chosen board. For example, to build for the
STM32F0DISCOVERY board, on may invoke the configure script as:

@code{../beebs/configure  --host=arm-none-eabi --with-chip=stm32f051 \
                          --with-board=stm32f0discovery}

@node Building
@section Building
@cindex building @value{BEEBS}

@value{BEEBS} is built with

@example
@kbd{make}
@end example

@quotation Note
@value{BEEBS} is not generally installed (it works, but there is no point).
@end quotation

The documentation may be created and installed in alternative formats (PDF,
Postscript, DVI, HTML) with for example:

@example
@kbd{make pdf}
@end example

If desired the documentation can be installed with

@example
@kbd{make install-pdf}
@end example

@node Running
@section Running
@cindex Running @value{BEEBS}

The tests are run using

@example
@kbd{make check}
@end example

@node Known Issues
@section Known Problems and Issues
@cindex problems
@cindex known issues
@cindex bugs
The following problems and issues are known about with @value{BEEBS}
@value{VERSION}. Notify other issues by email to
@email{beebs@@mageec.org}.

@itemize @bullet

@item
The configuration files, assume bash.

@end itemize

@node Adding a New Board to @value{BEEBS}
@chapter Adding a New Board to @value{BEEBS}
@cindex Adding a new board

@menu
* Where to add files::
* Configuration files::
* Header files::
* Board specific code::
* Calibration::
@end menu

@node Where to add files
@section Where to add files
@cindex where to add files

If the board uses a completely new architecture, you will need to
create a new subdirectory within the @file{config} directory.

@example
@kbd{cd config}
@kbd{mkdir @var{arch}}
@end example

The architecture name comes from the first part of the host triplet
(the @kbd{--host} configuration argument).

Within this @var{arch} directory create two separate directories for
board and chip configurations

@example
@kbd{cd @var{arch}}
@kbd{mkdir boards}
@kbd{mkdir chips}
@end example

If the architecture already has a board defined, these directories
will already exist.

Then for your new board, create a directory in the @kbd{chips}
directory for the chip it will use (if the directory does not already
exist).

@example
@kbd{cd chips}
@kbd{mkdir @var{chipname}}
@end example

The @var{chipname} corresponds to the argument given to
@kbd{--with-chip} when configuring.

Similarly create a directory in the @kbd{board} directory for the new
board. Since this is a new board, this directory will not already exist.

@example
@kbd{cd boards}
@kbd{mkdir @var{boardname}}
@end example

The @var{boardname} corresponds to the argument given to
@kbd{--with-board} when configuring.

@node Configuration files
@section Configuration files
@cindex configuration files
@cindex @file{arch.cfg}
@cindex @file{chip.cfg}
@cindex @file{board.cfg}

Configuration data may be defined for the architecture, for the chip
and for the board. These files are found respectively in

@example
@file{config/@var{arch}/arch.cfg}
@file{config/@var{arch}/boards/@var{boardname}/board.cfg}
@file{config/@var{arch}/chips/@var{chipname}/chip.cfg}
@end example

These take the form of @command{bash} shell scripts defining
environment variables. These include

@table @code
@item BOARD_CFLAGS
@cindex @code{BOARD_CFLAGS}
In @file{board.cfg}. Gives board specific CFLAGS

@item CHIP_CFLAGS
@cindex @code{CHIP_CFLAGS}
In @file{chip.cfg}. Gives chip specific CFLAGS

@item EXCLUDED_BENCHMARKS
@cindex @code{BOARD_CFLAGS}
Can be provided in @file{arch.cfg}, @file{board.cfg} or
@file{chip.cfg}. Gives a list of benchmarks not to run

@end table

Board specific and chip specific values are combined.

@node Header files
@section Header files
@cindex header files
@cindex @file{boardsupport.h}
@cindex @file{chipsupport.h}

There are two standard header files which may be defined:

@example
@file{config/@var{arch}/boards/@var{boardname}/boardsupport.h}
@file{config/@var{arch}/chips/@var{chipname}/chipsupport.h}
@end example

These are combined into the general header @file{support.h} which is
included by all benchmarks, and defines values which may be used by
the benchmarks. The values that may be defined are:

@table @code
@item BOARD_REPEAT_FACTOR
@cindex @code{BOARD_REPEAT_FACTOR}
Controls how often the tests are run, at a coarse granularity.
Fast boards may need a larger value, small boards a smaller value.
Default value 4096.

@end table

Other values may be defined for use in board specific code.

@node Board specific code
@section Board specific code
@cindex board specific code
@cindex @file{boardsupport.c}

Board specific code that is to be linked in to the benchmarks should
be defined in
@file{config/@var{arch}/boards/@var{boardname}/boardsupport.c}.
This file should define the following functions.

@table @code
@item initialize_board
@cindex @code{initialize_board}
Called to initialize the board (e.g. to clear the energy measurement
system).

@item start_trigger
@cindex @code{start_trigger}
Called at the start of the test run (e.g. to set a pin that will start
energy measurement).

@item stop_trigger
@cindex @code{stop_trigger}
Called at the end of the test run (e.g. to clear a pin that will stop
energy measurement).

@end table

It is usual for this file to include @file{support.h} to pick up any
board and chip specific definitions that may prove useful.

@node Calibration
@section Calibration
@cindex Calibration
@cindex @file{calibration}

Each benchmark is run a number of times to allow measurement collection. The
number of times can be scaled on a per benchmark basic by creating a file
called @file{calibration}. This file should be placed at
@file{config/@var{arch}/boards/@var{boardname}/calibration}.

Inside the file is a list of benchmark names followed by a scaling factor
(separated by a space).

@example
@kbd{2dfir 2}
@kbd{blowfish 3}
@end example

The numbers are used in the following expression to compute the number of runs:

@example
@kbd{(BOARD_REPEAT_FACTOR >> scale) >> extra}
@end example

In this code snippet, @kbd{scale} is the entry in the calibration file, and
@kbd{extra} is an extra scale factor specified in the source code file. The
@kbd{extra} allows default scaling for the benchmark to be provided.

@node Adding a New Benchmark to @value{BEEBS}
@chapter Adding a New Benchmark to @value{BEEBS}
@cindex Adding a new benchmark

@menu
* Benchmark structure::
@end menu

A new benchmark can easily be added to @value{BEEBS} by creating a new
directory with the benchmark's name under src. A template folder exists under
src with files which can be modified to compile the benchmark. The makefile.am
must be changed to reflect the name of the benchmark executable (which should
be the same as the folder name).

@node Benchmark structure
@section Benchmark structure
@cindex Benchmark structure

The main function to execute the benchmark should be called benchmark:

@example
@kbd{int benchmark(void)}
@kbd{@{}
@kbd{    return 0; // exit status}
@kbd{@}}
@end example

If necessary, initialisation code for the benchmark can be placed in
initialise_benchmark:

@example
@kbd{int initialise_benchmark(void)}
@kbd{@{}
@kbd{    return 0; // exit status}
@kbd{@}}
@end example

These functions are automatically called by the template main function (in
@file{src/main.c}). This file weakly links in both main and
initialise_benchmark, so that they can be overridden in a benchmark specific
fashion if necessary.

@node  GNU Free Documentation License
@chapter GNU Free Documentation License
@cindex license for beebs

@include fdl-1.2.texi

@node Index

@unnumbered Index

@printindex cp

@bye
