# [FE training-materials-updates] Improvements to the device tree lab

Michael Opdenacker michael.opdenacker at free-electrons.com
Tue Feb 4 08:39:48 CET 2014

Repository : git://git.free-electrons.com/training-materials.git

On branch  : master

>---------------------------------------------------------------

commit cff2cb0abdd6182f473896bf60d6ec27b0a9de8f
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Feb 4 08:37:34 2014 +0100

Improvements to the device tree lab

- In sync with what's in 3.13
- We are now using a phandle for i2c1
- Add more steps to the instructions
- Add runtime analysis of the DT
through /proc/device-tree and dtc.

Signed-off-by: Michael Opdenacker <michael.opdenacker at free-electrons.com>

>---------------------------------------------------------------

cff2cb0abdd6182f473896bf60d6ec27b0a9de8f
.../kernel-i2c-device-model.tex                    |   76 +++++++++++++++-----
1 file changed, 57 insertions(+), 19 deletions(-)

diff --git a/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex b/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
index 454e1e8..391f889 100644
--- a/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
+++ b/labs/kernel-i2c-device-model/kernel-i2c-device-model.tex
@@ -62,29 +62,67 @@ Now connect the nunchuk pins:
To let the Linux kernel handle a new device, the first thing is to add a
description for it in the board device tree.

-Do this by editing the \code{arch/arm/boot/dts/am335x-boneblack.dts}
-file describing all the buses and devices. You will need to follow the
-examples given in the lectures.
+We will have to do two things:

\begin{enumerate}
-\item Add a node declaring a second I2C bus (\code{i2c1}), functioning
-  at 100 KHz. As for \code{i2c0}, you will need to declare the base
-  address of its registers. Open the processor datasheet and find this
-    which you already know from the existing Device Tree (put an
-    underscore character in the middle of the address, as in
-    \code{FFFF_FFFF}... that's how addresses are written in the
-    datasheet). The base address for \code{i2c1} won't be far away.
-    If you do so, ignore the \code{pinctrl} properties for now.}.
-\item As a child node to this second bus, declare the \code{nunchuk}
-  device, choosing \code{nintendo,nunchuk} for its \code{compatible}
-  property. You find the I2C slave address of the nunchuk on the
-  nunckuk document that we have used earlier \footnote{This I2C slave
-    addressed is enforced by the device itself. You can't change it.}.
+\item Add a node declaring a second I2C bus (\code{i2c1})
+\item Add a child node to this bus, corresponding to the Nunchuk device.
\end{enumerate}

-Once this is done, recompile your DTB and copy the updated version to
-the tftp server home directory.
+\subsection{Declare a second I2C bus}
+
+First, find in which DTS file the first I2C bus (\code{i2c0}) for the
+BeagleBone Black is instantiated and in which file it is defined.
+
+Find the definitions for \code{i2c1}. What is the base address of its
+registers? Also find the same address in the processor datasheet
+\footnote{Tip: to do your search, put an underscore character in the middle
+of the address, as in \code{FFFF_FFFF}... that's how addresses are written in the
+TI datasheet).}.
+
+Then, imitating the definitions found for \code{i2c0},
+modify the \code{arch/arm/boot/dts/am335x-boneblack.dts}
+file to instantiate \code{i2c1}, functioning at 100 KHz.
+
+\subsection{Declare the Nunchuk device}
+
+As a child node to this second bus, declare the \code{nunchuk}
+device, choosing \code{nintendo,nunchuk} for its \code{compatible}
+property. You will find the I2C slave address of the nunchuk on the
+nunckuk document that we have used earlier \footnote{This I2C slave
+addressed is enforced by the device itself. You can't change it.}.
+
+\subsection{Checking the device tree on the running system}
+
+Now that you have modified the board device tree, recompile your
+DTB and copy the updated version to the tftp server home directory.
+
+Boot the board.
+
+Through the \code{/proc/device-tree} directory, it is possible to check
+the Device Tree settings that your system has loaded. That's useful when
+you are not sure exactly which settings were actually loaded.
+
+For example, you can check the presence of a new \code{nunchuk} node in
+
+\begin{verbatim}
+# find /proc/device-tree -name "*nunchuk*"
+/proc/device-tree/ocp/i2c at 4802a000/nunchuk at 52
+\end{verbatim}
+
+Using the Device Tree Compiler (\code{dtc}, which we put in the root
+filesystem), you can also check the whole Device Tree structure. That's
+better than checking the source files and includes in the source
+directory!
+
+\begin{verbatim}
+# dtc -I fs /proc/device-tree/
+\end{verbatim}
+
+Look for \code{i2c1} and \code{nunchuk} in the output of this command,
+and see where the nodes are instantiated. Don't hesitate to ask your
+instructor for questions!

\section{Implement a basic I2C driver for the nunchuk}