====== Command line interface ======

The IDE drive simulator implements a command line interface for debugging, configuration and experimentation. To connect, you must use a USB cable to connect to a host computer. When the device detects a host computer connected to either USB0 or USB1, it will simulate a serial port.

===== Connection =====

On Windows, use an app like HyperTerminal or [[https://www.putty.org|PuTTY]]. When the device is connected, Windows should indicate a new COM: port has been added. Windows 10 should include built in support via usbser.sys for the device when connected via a normal USB-A to micro USB cable, and will appear as a "USB Composite Device". Look in Device manager for a "USB Serial Device" to find the serial port number (for example, COM4).

On Linux and MacOS X, the device will appear under ///dev//, such as ///dev/ttyUSB0// or ///dev/cu.usbmodem1431//. You can use a tool such as [[https://en.wikipedia.org/wiki/Minicom|minicom]] or [[https://linux.die.net/man/1/screen|screen]] to open this device.

==== Settings ====

As the serial port is simulated, baud rate, handshaking and other serial settings should not matter.

===== Basic usage =====

The command line works similar to DOS. It will present a prompt representing the current directory, and provides a number of commands. The //help// command lists commands currently known to the command interpreter. You can also use //SD://, //USB0:// and //USB1:// to switch between the three drives, though they will be //Unavailable// if a storage device is not connected to the corresponding port.

===== Commands =====

==== Basic I/O ====

The board provides //dir//, //cd//, //ren// and //sd://, //usb0:// and //usb1:// to allow you to navigate the storage attached to the device and inspect their contents.

==== IDE ====

The IDE interface can be set to device 0 (also known as "master") or device 1 (also known as "slave") by command:

<code>interface set [master|slave]</code>

This can be combined with the autorun.txt startup file to ensure it's set every time the board starts up.

==== Disk ====

The //disk// command provides a means to manipulate the simulated disk.

<code>disk select (file)</code>
This command allows a new disk image to be selected. It simulates the drive being ejected and re-inserted, so if the host machine has disabled eject (e.g. MacOS X's default behaviour) the command will fail, as the disk cannot be removed.

<code>disk remove</code>
This command removes the disk, but as above, respects the eject disable flag, so it will fail if the host machine has locked the drive.

<code>disk disconnect</code>
This command forcibly removes the disk, and will cause I/O errors for the host machine if it continues to attempt to access it.

<code>disk search</code>
This command triggers the startup logic, where the IDE simulator will search for a disk image to use. See the 'startup' page for a description of this behaviour.

<code>disk describe (file)</code>
This command inspects a disk image and prints out relevant information, without having to select the image into the simulated disk drive. If no file is specified, it will describe the disk image currently loaded, if any.

<code>disk play (track)</code>
This command will start audio playback, if the disk image is a CD and the given track number is an audio track.

==== Debugging ====

These commands are provided to allow us to debug new games and applications in the field, where we may not have direct access to the hardware but still want to be able to add support.

<code>monitor</code>
This command will print out ATA requests (including ATAPI packets) as they arrive on the IDE interface. This allows for remote debugging to support new games and applications that may utilise functionality that's not currently implemented. Note that this command has a major impact on performance.

<code>history</code>
This command prints out the contents of the debug ring buffer, which is the same format as the //monitor// command but does not impact performance, and provides a way to inspect what has happened in the past.

<code>interface</code>
This command prints out the values currently contained in the various IDE and internal registers.

<code>processes</code>
This command lists the state of the various tasks within the system.

<code>status</code>
This command provides some convenient system status, including USB drivers and SD card state.