====== Lab Work 1 - Tools and Platform ======

The practical side of this course naturally requires a lot of programming work. We are going to write codes mainly using C programming language. Some assembly will be shown to demonstrate a few examples but students are not required to master them. The recommended development platform is Linux, but the module will show how it can be done on Windows (since this is what most students are familiar with).

====== Development Board ======

The development board used in this course will be the {{:archive:pgt302:raspberry_pi-quickstart.pdf|Raspberry Pi}} - a credit-card sized single-board computer developed by the [[https://www.raspberrypi.org/|Raspberry Pi Foundation]] (UK). The board is based on Broadcom's BCM2835 (ARM-based) Applications Processor. Information on the peripherals available on this particular microcontroller can be obtained from the official Raspberry Pi site ([[http://www.raspberrypi.org/wp-content/uploads/2012/02/BCM2835-ARM-Peripherals.pdf|here]]). A local copy for PGT302 students is available {{:archive:pgt302:bcm2835_peripherals.pdf|here}}. The [[http://elinux.org/RPi_Software#Overview|Embedded Linux wiki page]] provides a good documentation for this board (e.g. BCM2835 framebuffer info can be found [[http://elinux.org/RPi_Framebuffer|here]]).

===== Introduction =====

There have been a few versions of the board since it first came out in 2012 (pre-launched the year before). The ones available in our lab are the Model B+ Version 1. Here are some general specifications for this particular board:

  * A System on Chip BCM2835 package (with CPU & GPU) stacked on an SDRAM package
  * CPU is 700 MHz ARM1176JZF-S core (ARM11 family, ARMv6 instruction set)
  * GPU is 250 MHz Broadcom VideoCore IV (supports OpenGL, with video/audio? codec)
  * 512MB SDRAM shared by both GPU and CPU
  * 40-pin GPIO header connector (27-GPIO pins)
  * Powered by mini-USB connector (or GPIO header) requiring up to 600mA (3W)
  * 1 ethernet port, 4 USB ports (on-board 5-port USB hub)
  * HDMI video/audio output, separate 3.5mm audio jack

Each board optionally comes with a [[https://www.raspberrypi.org/downloads/noobs/|NOOBS]] (New Out Of the Box Software) micro-SD card. This is basically an OS installer (mostly Linux-based) which can be used to setup the micro-SD card for various applications programming tasks.

The recommended/official OS is [[https://www.raspberrypi.org/downloads/raspbian/|Raspbian]] (a Debian-based distribution tailored for Raspberry Pi). Other options are considered third-party images, which can be obtained [[https://www.raspberrypi.org/downloads/|here]].

The nice thing about this board is it has an HDMI output (which is becoming a norm for flat panel display unit). Connect a USB keyboard and a USB mouse, you get a PC running Debian 8-)

**Note:** We will only use Linux-based OS towards the end of this course.

===== DevInfo: Board Schematic =====

This is the schematic for Raspberry Pi Model B V1.2+.

{{ :archive:pgt302:raspberry_pi-schematic_model_b_1.2plus.png?direct&600 |Board Schematic}}

===== DevInfo: Peripherals Address Map =====

The information here is for (somewhat) low-level programming, that is if you are interested in accessing the hardware from your software code. If you are only interested in developing applications for Linux running on the Raspberry Pi, you most probably do not need this.

As with any development board, the first things you would like to know before you start programming is how to access (address?) the peripherals. The figure below (taken from BCM2835 ARM Peripherals documentation) shows an overview of the systems peripheral addressing information.

{{ :archive:pgt302:bcm2835_mmap.png?direct&600 |BCM2835 Peripherals Address Map}}

The thing to look for here is the I/O Peripherals (which includes the GPIO pins) and notice that there are three information entries - 0xF2000000 on the ARM Virtual Address, 0x20000000 on the ARM Physical Address (noted as set by arm_loader) and 0x7E000000 on the Video Core CPU Bus Address. You need these information to access the I/O peripherals.

===== DevInfo: GPIO Header Information =====

This is the information you need to connect the Pi to various peripherals

{{ :archive:pgt302:rpi_gpio_pinouts.png?direct&600 |GPIO Header}}

You can find the GPIO that you need to use on the respective headers (in our case, it is the 40-pin header).

{{ :archive:pgt302:rpi_gpio_pinouts_2.png?direct&600 |Alternative image}}

//**Note**: I got these images from the internet. Credits due to the original owner(s).//

====== Preparing SD Card ======

//**Note**: As mentioned earlier, we will be using bare-metal programming at first, and then, progress towards using Raspbian.//

{{page>raspi:raspi_prepare_card&noheader}}

====== Development Tool ======

We usually have a more powerful machine on our desktop compared to our target embedded platform. It is therefore more convenient to compile the target embedded software on our desktop (another reason would be simply because our platform is NOT capable of compiling its own program). This process usually requires us to have/build [[https://en.wikipedia.org/wiki/Cross_compiler|cross-compilers]] - compiler that runs on a host machine, but produces binary/executable for a target machine. You can read about [[notes:cross_compiler|my experience on cross-compilation here]].

A simple script to build a cross-compiler for Pi is available in [[https://github.com/azman/my1ubuild|my1ubuild project]]. The project is actually a repository of build scripts for various tools. The one we need here is [[https://github.com/azman/my1ubuild/blob/master/arm-gcc.build|arm-gcc.build]].

**Note**: Video guides are [[https://www.youtube.com/watch?v=7HLTYJG5p3A&list=PLKQoMxsWIO1wrfPfnvZWFefhiAYrfrej6|available on YouTube]]

===== Linux Platform =====

You are encouraged (...required, actually) to try to build your own cross-compiler using the script mentioned above. If you have problems, you can always ask your instructor.

===== Windows Platform =====

You can either try to build your own cross-compiler on Windows using the script mentioned above, OR you can simply get the one I have already built for you.

==== Building a Cross-compiler ====

//**Note20211027** Notes on setting up latest MinGW environment is available [[notes:mingw_compiler|here]].//

We need to have a working compiler. I prefer [[http://www.mingw.org/|MinGW (Minimalist GNU for Windows)]], so that is what I'll use to demonstrate. Download the mingw-get installer from [[https://sourceforge.net/projects/mingw/files/Installer/mingw-get|here]]. At the moment, the latest version is 0.6.2-beta-20131004-1, so I download ''mingw-get-0.6.2-mingw32-beta-20131004-1-bin.zip''. 

I want my compiler in ''C:\Users\Public\Tool\mingw'', so I created that folder and extract the contents into that folder. Open up a command prompt, change path <code>cd C:\Users\Public\Tool\mingw\bin</code> and run the following:
  * ''mingw-get install "gcc=5.3.*"''
  * ''mingw-get install "g++=5.3.*"''
  * ''mingw-get install gmp''
  * ''mingw-get install mpfr''
  * ''mingw-get install mpc''
  * ''mingw-get install msys''
  * ''mingw-get install msys-wget-bin''
Edit ''C:\Users\Public\Tool\mingw\msys\1.0\etc\profile'' and comment the last line which is a ''cd $HOME'' command (insert a ''#'' at the beginning of the line).

To make things easier for you, I have written a [[https://github.com/my1matrix/mingw4user/raw/master/msys.vbs|Windows script]] to create a link in the Explorer popup menu. Copy this script into ''C:\Users\Public\Tool\mingw''. Running this script (*Hint*: double-click) will install (or remove if already installed) a pop-up context menu entry (''MinGW Shell'') whenever you right-click on a folder in Windows Explorer.

Get [[https://github.com/azman/my1ubuild/blob/master/arm-gcc.build|arm-gcc.build]] and place it in ''C:\Users\Public\Tool\my1ubuild''. Open a MinGW Shell at this location and run <code bash>TOOL_PATH=/c/users/public/tool sh arm-gcc.build</code>

The script will download the required ''binutils'' and ''gcc'' tarballs and build them. After a while, you should get your cross compiler at ''C:\Users\Public\Tool\xtool-arm''.

==== Pre-built Cross-compiler ====

Or, if you just want to get on with your work, here are what you need to download:
  * [[http://azman.unimap.edu.my/storage/mingw-20171031.zip|MinGW]] ([[http://azman.unimap.edu.my/storage/mingw-20171031.zip.md5|MD5]]:15e5e4d1f4b5a12f5c16926567b629fb) - [[http://www.mingw.org/|Minimalist GNU for Windows]] utilities, which includes msys that provides a make environment. This is a local copy for your convenience. If you want, you can install your own from 'original' source using mingw-get (this is exactly what I used to create that zip file for you to download).
  * [[http://azman.unimap.edu.my/storage/xtool-arm-20171031.zip|ARM Cross-Compiler]] ([[http://azman.unimap.edu.my/storage/xtool-arm-20171031.zip.md5|MD5]]:876a2fb45779ae726ce07c4f78e63101) - The compiler that you need to compile your bare-metal codes. Either build one on your own as mentioned earlier, or simply use this.

Note that these binaries were built using Windows 7 running in VirtualBox on my Slackware 14.1 installation. But I have tested it on Windows 8 and Windows 10 machines, and I have no problems so far.

Setting-up the cross compiler:
  - Once you have downloaded the files, extract them to //C:\Users\Public\Tool// (so, you should have an //xtool-arm// folder there with a //bin// sub-directory). The location //C:\Users\Public\Tool// is referred to as TOOLPATH in this course), you should have the MinGW compiler in %TOOLPATH%\mingw and the ARM cross-compiler in %TOOLPATH%\xtool-arm.
  - It would be handy to have a shortcut on the Explorer popup menu to open up a MinGW shell in the folder being viewed. Double-click ''msys.vbs'' (should be in %TOOLPATH%\mingw)  to toggle this feature. For the script to actually open up in a particular folder, browse to mingw folder and edit msys\1.0\etc\profile and comment (insert '#' character at the beginning of) the last line (should be ''cd $HOME'').
    * if you get a popup message saying ''Windows Script Host Access is disabled on this machine'', you will have to use registry editor to fix that. Type ''regedit'' in a command prompt (you must be ad adminstrator for this... by default, the first account IS). Look for ''HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows Script Host\Settings'' - and make sure the ''Enabled'' value is set to 1. (You may also need to change one in ''HKEY_LOCAL_MACHINE'')
  - To start working on a project, open your project folder in Windows Explorer and right-click to get the usual popup menu. You should now have a 'MinGW Shell' link. It should open up a terminal (shell) window in that folder. This is where we will do most of the compilation work at the early stages (bare-metal programming).

==== Code Editor ====

As mentioned in your programming course, you can use any text editor to write your program (even Windows Notepad!), but it is nice (and useful) to have at least syntax highlighting feature - a 'proper' code editor. For this, I would like to recommend [[http://www.geany.org/|Geany]], a GTK-based cross-platform text editor. I use this a lot when coding on Linux. You can download a Windows installer [[http://www.geany.org/Download/Releases|here]]. It can be installed as normal user (no admin access required!).

==== Source Code Management ====

Most coding projects tend to use source code management (SCM) software, and I recommend [[https://git-scm.com/|git]] (I have [[notes:git|my own notes]] on this). It is also [[https://git-scm.com/download/win|available on Windows]].

==== Bare-metal Library Code ====

I have one available - [[http://github.com/azman/my1barepi|my1barepi]].