yocto-public/2-usage/machinecreate.md

# Create a Machine / Board Support Package

## Creation

In the layer directory:
```sh
mkdir $LAYER/conf/machine

MACHINE=my-machine
touch $LAYER/conf/machine/$MACHINE.conf
```

See below for an interactive script to create a machine.

### Machine conf. file

Edit `$LAYER/conf/machine/$MACHINE.conf` to set variables:

| Variable | Role | Link |
|---|---|---|
| `TARGET_ARCH` | CPU architecture (`arm`, `i386`, `x86_64`, etc.) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TARGET_ARCH)
| `PREFERRED_PROVIDER_virtual/kernel` | Linux kernel recipe to use (`linux-yocto`) |
| `MACHINE_FEATURES` | See [Combined Features](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-COMBINED_FEATURES) |
| `SERIAL_CONSOLES` | Serial consoles to enable & their configurations (`115200;ttyS0 115200;ttyS1`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-SERIAL_CONSOLES) |
| `KERNEL_IMAGETYPE` | Type of the kernel image (default: `zImage`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-KERNEL_IMAGETYPE) |
| `IMAGE_FSTYPES` | Type of the output filesystem image (default: `ext3 tar.bz2`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-IMAGE_TYPES) |

### Kernel config file

Bitbake builds the kernel `.config` file using configuration fragments from the kernel recipe.

There are two ways to setup kernel configuration:
- Using `.scc` files
- Using `.cfg` files

Both files can be added to `SRC_URI` in the kernel recipe to be used.

See `$POKY/meta/recipes-kernel/linux` for recipe examples

#### `.cfg` files

`.cfg` files contains fragments of kernel `.config` file.

If multiple cfg files are added to the recipe, the values contained in the last included will override other values that were already set.

You can view the resulting kernel `.config` with the standard kernel menuconfig UI:
```sh
bitbake virtual/kernel -c menuconfig
```

_Extracting a config fragment:_

- Go to `$POKY/build/tmp/work/*/$KERNEL_RECIPE_NAME/*/$KERNEL_RECIPE_NAME-*-build`
- Use a diff tool (`vimdiff`, `meld`, `kdiff3`) to list differences between `.config` and `.config.old`

<info data-markdown>
At this time, there is no practical tool to create configuration fragments.
</info>


#### `.scc` files

`.scc` files are like a wrapper around .cfg files.

They can include multiple `.cfg` or `.scc`, define which kernel branch to use, the architecture and other things.

```
define KMACHINE my-machine
define KTYPE tiny
define KARCH i386

kconf hardware general.cfg
kconf hardware liveboot.cfg

include ktypes/tiny/tiny.scc
branch my-machine

include my-machine.scc
```

[More](http://www.yoctoproject.org/docs/1.8/mega-manual/mega-manual.html#scc-reference)

### Formfactor

<todo></todo>

```cfg
HAVE_TOUCHSCREEN=0
HAVE_KEYBOARD=1

# Display rotation, size, colors, ...
DISPLAY_CAN_ROTATE=0
DISPLAY_ORIENTATION=0
#DISPLAY_WIDTH_PIXELS=640
#DISPLAY_HEIGHT_PIXELS=480
#DISPLAY_BPP=16
DISPLAY_DPI=150
DISPLAY_SUBPIXEL_ORDER=vrgb
```

## Interactive script


<info data-markdown>
The script `yocto-bsp create <layer_name> <target_arch>` creates a layer named `<layer_name>` with a BSP for the architecture `<target_arch>` into.<br/>
You can get the list of supported arch with `yocto-bsp list karch`
</info>

This is an interactive script to create a BSP contained in a new layer:
```bash
yocto-bsp create my-machine i386
# Checking basic git connectivity...
# Done.
#
# Would you like to use the default (3.14) kernel? (y/n) [default: y]
# Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
# Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.14.git...
# Please choose a machine branch to base this BSP on: [default: standard/base]
# 	1) standard/arm-versatile-926ejs
# 	2) standard/base
# 	3) standard/beagleboard
# 	4) standard/beaglebone
# 	5) standard/ck
# 	6) standard/common-pc/base
# 	7) standard/edgerouter
# 	8) standard/fsl-mpc8315e-rdb
# 	9) standard/mti-malta32
# 	10) standard/mti-malta64
# 	11) standard/qemuarm64
# 	12) standard/qemuppc
# 	13) standard/routerstationpro
# 2
# Do you need SMP support? (y/n) [default: y] n
# Which machine tuning would you like to use? [default: tune_core2]
# 	1) i586 tuning optimizations
# 	2) Atom tuning optimizations
# 	3) Core2 tuning optimizations
# 2
# Do you need support for X? (y/n) [default: y] n
# Does your BSP have a touchscreen? (y/n) [default: n] n
# Does your BSP have a keyboard? (y/n) [default: y] y
#
# New i386 BSP created in meta-my-machine
```

<warn data-markdown>Don't forget to add the layer to `BBLAYER` if you want to use it</warn>


### Generated tree

```text
poky/build/meta-my-machine
├── binary
├── conf
│   ├── layer.conf                     => Layer configuration file
│   └── machine
│       └── my-machine.conf                => Machine configuration file
├── COPYING.MIT
├── README
├── README.sources
├── recipes-bsp
│   └── formfactor
│       ├── formfactor
│       │   └── my-machine
│       │       └── machconfig         => Input device support
│       └── formfactor_0.0.bbappend
├── recipes-graphics                   => Empty, can be deleted
│   └── xorg-xserver
│       └── xserver-xf86-config
│           └── my-machine
└── recipes-kernel
		└── linux
				├── files
				│   ├── my-machine.cfg     => Kernel configuration file
				│   ├── my-machine-preempt-rt.scc
				│   ├── my-machine.scc
				│   ├── my-machine-standard.scc
				│   ├── my-machine-tiny.scc
				│   ├── my-machine-user-config.cfg
				│   ├── my-machine-user-features.scc
				│   └── my-machine-user-patches.scc
				└── linux-yocto_3.14.bbappend      => Kernel recipe
```