** @name cdilink.txt Description of CD-i Link program.
* 
* @section Copyright (c) 2005, CD-i Fan
* You are free to distribute the cdilink program for non-commercial purposes,
* provided you include this documentation file.
*
* The source for cdilink is not currently available, but it will
* be released under the GNU General Public License, version 2.
*
* @author CD-i Fan
*
* @version 0.5.1
*
* @history
* @rev 2005/04/01 cdifan Created.

The purpose of the CD-i Link program (cdilink) is to communicate with a
CD-i player over a serial connection. The communication uses the "stub"
protocol; see the file stub.txt that you should have received with this
file for more information.

The primary purpose of cdilink is to upload the system ROMs from a CD-i
player to a PC for use with a CD-i emulator, but you can also upload
or download other files and display information about the CD-i player.
This allows you to inspect and modify the contents of the player NVRAM
(e.g., highscore files) and to to inspect the contents of CD-i discs.

The CD-i system ROM files are copyrighted and cannot be freely
redistributed. Using the ROM files for emulation purposes should be
allowed as long as you own the CD-i player that the ROM files were
originally obtained from.

The "stub" protocol used by cdilink supports basic services such as
uploading from and downloading to player memory and a limited form of
remote debugging and execution. The cdilink program builds upon these
basics to provide higher-level services such as locating and uploading the
system ROMs, determining the CD-i player type, displaying the contents
of directories on the CD-i player and copying files between the CD-i
player and the PC. See the option listing at the end of this document
for more information about the full capabilities of cdilink.

To use cdilink with your CD-i player you need a so-called CD-i nullmodem
cable. Such a cable used to come with the CD-Interlink disc but you can
easily make one yourself or perhaps borrow one from a fellow CD-i fan.
See the file cables.txt for more information.

The nullmodem cable needs to be connected to the serial port of your
CD-i player. It is typically located at the back of the player and often
marked "Input 2"; for some players you need to use a port splitter cable
on the front port. On consumer players the serial port generally has a
MiniDIN-8 connector; for the Philips CD-i 605 authoring player you need
to use the DB-9 connector on the back marked "Input 3".

Most Philips CD-i players support the so-called "download subset"
of the "stub" protocol, which is enough to let cdilink download a full
implementation of the protocol (cdistub) into the player. If your player
does not support this, you will need to use a CD-i disc containing the
cdi_stub program. A disc image file of the cdi_stub disc suitable for
burning should be available from the same place where you got cdilink.

The "no extra memory" configuration of the CD-i 605 player does not
support access to the serial port from a CD-i program; you will need to
configure some extra memory or use a605stub instead of cdistub.

For uploading the CD-i system ROMs you need to connect the nullmodem
cable and type the following command line:

	cdilink -roms

When cdilink says "Waiting for stub..." you must turn on the CD-i player
(if your player supports the download subset) or start the cdi_stub disc
(if your player does not support the download subset).

If you've connected everything properly, cdilink will recognize the CD-i
player and start communicating with it. A typical cdilink -roms session
looks like this:

	CD-i Link version 0.5.x
	Waiting for stub...
	Downloading cdistub...
	00008XXX
	Ending download stub...
	CD-i Stub version 0.5.x
	Reading module directory...
	Reading module information...
	00XXXXXX
	Found XX modules
	Reading memory list...
	Building ROM list...
	Uploading cdixxxy.rom (512K)...
	00XXXXXX
	Uploading xmpegy.rom (128K)...
	00EXXXXX
	Ending stub...
	Done!

The names of the uploaded ROM files will vary depending on your CD-i
player model; if cdilink does not recognize your player model it will
use names like cdi000x.rom, xmpegx0.rom or rom000x.rom.

The automatic ROM location and player model recognition is very general
and should work on all CD-i player models, but it has only been tested
on a limited set of CD-i players.

You can also generate an extensive information file about your player
by adding the "-info" option to the command line:

	cdilink -info -roms

This should always be done if cdilink does not recognize your player model
or the automatic ROM location algorithm doesn't work; in the latter case
you generate just eh information file by leaving out the "-roms" option:

	cdilink -info

The generated information file will be named something of the form
cdixxxy.txt that will vary according to the player model.

If your player model or digital video cartridge type isn't correctly
determined by cdilink, it would be helpful if you could send me the
information file, which is just a text file. Please do not send the
ROM files as they are copyrighted and cannot be freely redistributed.
You can reach me via email using cdifan (at) gmail (dot) com.

The above assumes that you've connected the nullmodem cable to the first
serial port (COM1) of the PC. If you used a different port you need
to add a "-port" option to specify the port:

	cdilink -port N -roms

Here N is the number of the serial port (the default is 1 for COM1).
If your serial port is not named COMx you have to use the full name,
e.g. AUX or COM3A.

The default communication speed is 9600 baud; at this speed it will
take at least 10 minutes to upload the system ROMs from the player. If
you have a fast enough PC and CD-i player you can try to increase the
communication speed to 19200 or even 38400 baud by adding the option
"-baud 19200" or "-baud 38400", respectively.

The protocol includes CRC checks so you will not get incorrect data even
if your PC or CD-i player cannot handle the higher baudrate.

The cdilink program supports a large number of options; only a few have
been described above. The general command line syntax for cdilink is:

	cdlink OPTION...

If no options are used, a usage message will be displayed that lists the
available options. Many options can be abbreviated; this is indicated
by enclosing the optional part of the option name in square brackets,
e.g. -e[nd]. Options for basic functionality can all be abbreviated to
single letters. Option arguments must follow the option, separated by
one or more spaces and will continue to the next option. 

As of version 0.5.1, cdilink supports the following options:

-roms [FILE...]

	Locates and uploads the CD-i player ROMs to the specified files,
	in address order. If no arguments is specified the names of the
	files are determined using the automatic player model algorithm.
	If the player model or ROM type isn't recognized the name of the
	file will be of the form cdi000x.rom, xmpegx0.rom or rom000x.rom.

-info[rmation] [FILE]

	Writes extensive information about the CD-i player to a file with
	the specified name; if no argument is specified the name of the
	file is determined using the automatic player model algorithm.
	If the player model isn't recognized, the name of the file will
	be cdi000x.txt.

-p[ort] N

	Uses the specified serial port to communicate with the CD-i
	player; the default is 1 (the first serial port). Serial port
	numbers refer to the COMx ports; you can also use the full port
	name, e.g. COM1, AUX or COM3A.

	You can also use a port name of the form term:NAME to connect
	to terminal port NAME of a running CD-i emulator program.

-r[eset]

	Attempts to reset CD-i player by sending a break signal over the
	serial connection. This only works in conjunction with a -p[ort]
	option argument of the form term:NAME.

-w[ait] [BAUDRATE]

	Waits for stub activation using the specified baudrate; the
	default is to wait at 9600 baud. This option is the default if
	neither -c[ontinue] nor -t[erminal] is specified.

-c[ontinue] [BAUDRATE]

	Attempts to continue session using the specified baudrate; if no
	baudrate is specified the communication speed is not changed. This
	option can also be used together with the -w[ait] option to
	specify the baudrate to expect after the initial stub activation.

-b[audrate] [BAUDRATE]

	Negotiates with the stub program to change to the highest baudrate
	not exceeding BAUDRATE; if no argument is specified the highest
	supported baudrate is used, typically 38400. The default is to
	retain the baudrate specified with -w[ait] or -c[ontinue].

-s[tub] [FILE]

	Downloads the specified stub program into the CD-i player; the
	default is to use the builtin cdistub program (see also the
	-dump option). Additional stub programs for special purposes
	should be available from the same place where you got cdilink.

-n[ostub]

	Skips downloading of stub program. If this option is used,
	cdilink will use the already running stub program; in the case
	of a download subset this means that uploading and information
	functions will not work.

-e[nd]

	Ends the stub program after all operations are performed.
	This will usually reset the CD-i player; ending the download
	subset (this can happen if the -n[ostub] option was used) will
	normally continue the CD-i player startup process. This option
	is the default unless -k[eep], -c[ontinue] or -i[nteractive]
	is specified.

-k[eep]

	Keeps the stub program active after all operations are performed.
	This can be used to run multiple invocations of cdilink without
	having to turn the player on and off. The next cdilink invocation
	should use the -c[ontinue] option for this to work.

-v[erbose]

	Verbosely displays the "stub" protocol messages being sent and
	received by cdilink; repeating this option will also display
	the data content in the messages that is normally omitted to
	keep the display readable.

-a[ddress] ADDR

	Specifies address for subsequent -u[p][load] or -d[own][load]
	options. The address is automatically incremented by each
	upload or download, but the initial address must be specified.
	The address is always specified in hexadecimal, but an initial
	"0x" or "$" is allowed.

-[si]z[e] SIZE

	Specifies size for next -u[p][load] or -d[own][load] option.
	A size must be specified before each -u[p][load] option; the
	default for -d[own][load] options is to use the size of the file
	to be downloaded.

	The size can be specified in decimal or hexadecimal; the latter
	is indicated by prefixing the size with "0x" or "$". A trailing
	capital letter "K" or "M" can be added to indicate a number of
	Kilobytes (1024) or Megabytes (1048576), e.g. 512K.

-u[p][load] FILE

	Uploads from the CD-i player memory to the specified file.
	An upload address must be specified with the -a[ddress] option
	before the first -u[p][load] option; an upload size must be
	specified with the -[si]z[e] option before each -u[p][load] option.

-d[own][load] FILE...

	Downloads the specified files into the CD-i player memory.
	A download address must be specified with the -a[ddress] option
	before the first -d[own][load] option. If no download size has
	been specified with the -[si]z[e] option, the default is to use
	the size of the file.

-[e]x[ecute] [ADDR]

	Starts execution of the CD-i player at the specified address;
	if no argument is specified the default is to use the address
	specified with the last preceding -a[ddress] option.

-t[erminal]

	Enter terminal emulation mode after all operations are performed.
	The emulation is for a conventional "dumb" terminal without
	cursor addressing. You can switch from terminal emulation mode
	to interactive mode by using the Ctrl-] key combination.

-i[nteractive]

	Enter interactive command mode. In interactive command mode, most
	cdilink options can be entered as commands; the initial minus
	sign can be omitted. All commands will have effect immediately,
	e.g. e[nd] will immediately end the stub program. Use t[erminal]
	to enter terminal emulation mode or q[uit] to exit cdilink.
	Use normal option syntax to combine multiple cdilink options in
	a single command line.

-q[uit]

	Quits interactive mode. This option is ignored in non-interactive
	command mode. This will leave the stub active; you can combine
	with the -e[nd] option to end the stub first, e.g. q[uit] -e[nd].

-ch[directory] DIR

	Changes the current directory of the CD-i player to the
	specified directory, e.g. /cd for the root of a CD-i disc.
	You cannot change directories to /nvr (NVRAM).

-di[rectory] [DIR]

	Displays the contents of the specified directory from the CD-i
	player to the screen, the default is the current directory. To
	display the contents of the NVRAM, use /nvr.

-li[st] FILE...

	List the specified files from the CD-i player to the screen,
	with newline translation. This is especially useful for NVRAM
	text files, e.g. /nvr/csd but can also be used for text files
	from a CD-i disc, e.g. the abstract or bibliographic file.

-u[p]c[opy] FILE...

	Copies the specified files from the CD-i player to the current
	directory. Newline translation is not performated. This can be
	used to upload files from NVRAM or from a CD-i disc.

-d[own]c[opy] FILE...

	Copies the specified files from the current directory to the
	CD-i player. Newline translation is not performed. This can be
	used to download files to NVRAM.

-del[ete] FILE...

	Deletes the specified files from the CD-i player. This can be
	used to make space in NVRAM. Take care not to delete important
	player files, e.g. /nvr/csd!

-type

	Displays the CD-i player, board and digital video cartridge type
	as determined from the contents of the system ROMs. 

-mem[ory][list]

	Displays list of memory areas from the CD-i player. This will
	also display the available free space.

-modg[roups]

	Displays list of module groups from the CD-i player, this can
	be useful to find the player ROMs manually.

-mod[ules]

	Displays list of modules and their attributes from the CD-i
	player, useful to determine the player type manually.

-romlist

	Locates CD-i player ROM addresses and displays their locations
	and types.

-rules FILE

	Reads rules for determining CD-i player and ROM type from
	the specified file; the default is to use the builtin file
	cditypes.rul (see also the -dump option).

-dump [FILE]

	Dumps the specified builtin file to the current directory; if
	no arguments are present a list of the builtin files is displayed.

Here is an example of a cdilink session, with commentary:

	cdilink -k                      Download cdistub and keep it active
	
	cdilink -c -b 19200             Continue by changing baudrate
	
	cdilink -c -dir /nvr            List contents of NVRAM
	
	cdilink -c -ucopy /nvr/HISCORE  Uploads HISCORE file to PC
	
	cdilink -c -del /nvr/HISCORE    Deletes HISCORE file from NVRAM

	cdilink -c -mem                 Display player free memory
	
	cdilink -c -chdir /cd           Change directory to root of CD-i

	cdilink -c -dir                 Display contents of CD-i

	cdilink -c -e                   Ends stub program

You could also use interactive mode to make this easier:

	cdlink -b 19200 -i

This will result in a cdilink: prompt at which you could type
the corresponding commands:

	dir /nvr
	ucopy /nvr/HISCORE
	del /nvr/HISCORE
	mem
	chdir /cd
	dir
	quit -e

A CD-i developer might use CD-i link to download test programs into the
player and would have no need for cdistub. He/she would use invocations
like this one:

	cdilink -n -a 8000 -d cdiprog -e

In this case special arrangements need to be made so that the program
will run and can find its data, but there do not belong here.

