# Introduction
This guide demonstrates how to quickly start Linux on the AM64x General Purpose EVM (GP EVM) through SD card.
This can be done from any of the three main PC platforms: Windows, Linux and macOS.
Please refer to [AM64x GP EVM](https://www.ti.com/tool/TMDS64GPEVM) for detailed information
about the EVM.
# Hardware Setup
In addition to the GP EVM itself, the following hardware is needed:
* 12V DC power supply (please refer to the [AM64x GP EVM User's Guide](https://www.ti.com/lit/spruix0) for recommended power supply)
* Micro-SD card reader
* Micro-SD card **(16GB or larger)**
* USB Micro-B cable for UART serial communication
* Ethernet cable
The figure below shows the basic hardware setup required to start Linux on the EVM.
![Alt Text - AM64x GP EVM setup](./images/am64x_gp_evm_setup.jpg)
### EVM Power-On/Off Procedure
[[r! WARNING
Proper power-on/off procedure must be followed to avoid potential short circuit which can damage the EVM.
]]
Please follow section 3.3 Power-On/Off Procedures of the [AM64x GP EVM User's Guide](https://www.ti.com/lit/spruix0)
to turn on/off the power for the EVM.
In summary, to power on the EVM, you'll need to:
1. place EVM power switch in OFF position as shown in the picture above,
2. with the 12v DC power supply disconnected from AC power, plug in the power supply to the EVM power jack,
3. connect the power supply to AC power,
4. place EVM power switch in ON position.
To power off the EVM, you'll need to:
1. place EVM power switch in OFF position,
2. disconnect the power supply from AC power,
3. unplug the power supply from the EVM if this is needed.
### EVM Boot Mode Setting
The simplest way to run Linux on AM64x EVM is through an SD card. For that, the EVM will need to be
configured for SD card boot. Refer to [AM64x GP EVM User's Guide](https://www.ti.com/lit/spruix0) for
detailed information about boot mode configurations. For quick reference, the figure below shows the
boot mode switch setting for SD card boot.
![Alt Text - AM64x GP EVM SD card boot mode](./images/am64x_gp_evm_sdcard_boot_mode2.jpg)
# Software Setup
To boot Linux on AM64x EVM through an SD card, a Linux bootable SD card needs to be created. In order
to do that, an AM64x Linux WIC image and an image writing utility are needed.
### Getting the AM64x Linux WIC Image
Go to [Processor-SDK download page](https://www.ti.com/tool/PROCESSOR-SDK-AM64X). Click "Downloads" and
then choose either PROCESSOR-SDK-LINUX-AM64X or PROCESSOR-SDK-LINUX-RT-AM64X. Click "Download options"
and then in the pop-up window download the WIC image tisdk-default-image-am64xx-evm.wic.xz.
The WIC image is also available inside the SDK which can be downloaded from the same pop-up window.
After SDK is installed, tisdk-default-image-am64xx-evm.wic.xz is located at
processor-sdk-install-folder/filesystem.
### Writing the WIC Image to SD Card
An image writing utility is needed to write the WIC image to an SD card. An open source project,
[balenaEtcher](https://www.balena.io/etcher/), is recommended for this purpose, which works in
Windows, macOS and Linux.
After balenaEtcher is installed, insert a micro SD card into the USB SD card writer and start Etcher.
Choose the compressed WIC image obtained in previous step, choose the USB SD card writer as the
target, and then click "Flash". Etcher will decompress the image and write it to the SD card,
as shown below.
![Alt Text - balenaEtcher writing SD card](./images/SDcard_writing.png)
# Establishing a Serial Connection with the EVM
Connect the USB Micro-B cable to the USB Micro-B debug console on the EVM, which is right next to the
power ON/OFF switch. Connect the other end to the host PC. Then open a serial port console on the PC,
according to the procedures described below for Linux, Windows or macOS.
Please note that when the serial port console opens, it will remain blank until the EVM powers up.
### Connecting with Linux
1. Determine the device name associated with the EVM by running the following command on your Linux PC:
```
dmesg | grep ttyUSB
```
You should see four results similar to this example:
```
usb 2-1.3: FTDI USB Serial Device converter now attached to ttyUSB0
usb 2-1.3: FTDI USB Serial Device converter now attached to ttyUSB1
usb 2-1.3: FTDI USB Serial Device converter now attached to ttyUSB2
usb 2-1.3: FTDI USB Serial Device converter now attached to ttyUSB3
```
The first one should be used to open a serial port console.
2. Use the "screen" command to open a serial port console. Below is what the command looks like for
the example given above:
```
screen /dev/ttyUSB0 115200
```
### Connecting with Windows
1. Open Windows Device Manager and it should show 4 COM ports associated with the EVM, as shown below:
![Alt Text - Windows COM ports](./images/windows_com_ports_gp_evm.jpg)
2. Use a serial terminal emulator such as TeraTerm to connect to the first port. Configure the
serial port setting to 115200 baud rate, 8 bit, no parity, 1 stop bit, no flow control, as shown below:
![Alt Text - serial port setting](./images/serial_port_setting_gp_evm.jpg)
### Connecting with MacOS
1. Determine the device name associated with the EVM by running this command:
```
ls /dev/cu*
```
You should see /dev/cu.usbserial-xxx listed, similar to the example below:
```
/dev/cu.usbserial-432010100850
/dev/cu.usbserial-432010100851
/dev/cu.usbserial-432010100852
/dev/cu.usbserial-432010100853
```
The first one should be used to open a serial port console.
2. Use the "screen" command to open a serial port console. Below is what the command looks like for
the example given above:
```
screen /dev/cu.usbserial-432010100850 115200
```
# Booting Linux on the EVM
Assuming you have made a Micro-SD card with AM64x Linux image and connected to the EVM's serial
port, follow steps listed below to boot the EVM to Linux:
1. Make sure the EVM is powered off. Insert the Micro-SD card to the EVM (the side of the card with contacts should face downward).
2. Make sure the EVM boot mode switches are set properly for SD card boot as described earlier.
3. Connect one end of an Ethernet cable to the EVM and the other end to a router.
4. Follow the power-on procedure provided above to turn on the power for the EVM.
5. The EVM should boot and the booting progress should display in the serial console output. At the end
of booting, the Arago login prompt will appear. Just enter "root" to log in, as shown below:
![Alt Text - Linux log in](./images/linux_login.jpg)
You are in Linux on your AM64x GP EVM now.
# Next Steps
After booting the AM64x GP EVM to Linux, users are encouraged to explore more, for example:
* Try the out-of-box benchmark demo according to
[Benchmark Demo User's Guide](https://software-dl.ti.com/processor-sdk-linux/esd/AM64X/latest/exports/docs/system/Demo_User_Guides/Benchmark_Demo_User_Guide.html).
* Dive into Linux. Please refer to [AM64x Processor-SDK Documentation](https://software-dl.ti.com/processor-sdk-linux/esd/AM64X/latest/exports/docs/devices/AM64X/Overview.html).
# Troubleshooting
Here we list some common problems which may happen during this exercise and the corresponding solutions.
1. **The EVM doesn't boot and the serial console doesn't display anything.**
First, make sure the Micro-SD card is flashed with the right WIC image.
Then double check the EVM boot mode setting and it must be configured for SD card boot.
2. **The EVM boots but it doesn't end up with the login prompt.**
This is likely caused by having a Micro-SD card with size less than 16GB. Please use a card with
16GB or larger capacity.
If you encounter any other issues not listed here, please go to
[E2E Processor Forum](https://e2e.ti.com/support/processors-group/processors/f/processors-forum) to search
for answers or post a new question.