GPICD Users Manual - Command Line Interpreter

GPICD - The GNU PIC Programmer and In-Circuit Debugger

3. The Command Line Interpreter

The command line interpreter gpicd-cmd can be used either in shell-command or interactive mode.
The shell-command mode allows to perform ICSP (In-Circuit Serial Programming) operations directly from your prefered OS shell. For example, "gpicd-cmd read -d" shows the content of the EEPROM; "gpicd-cmd load myprog.hex" loads an iHEX program into the program memory, etc.
The interactive mode is a permanent session that prompt you for GPICD commands. In this mode, all ICSP and ICD (In-Circuit Debugging) operations are available.

Launching the GPICD Command Line Interpreter

$ gpicd-cmd [-dev device] [-v] [-p type] [command ...]

-dev device : Use parport device instead of default /dev/parport0
-v : Display ICSP operations to stderr while accessing PIC memory (debug purpose only)
-p type : Select a processor type. Default is PIC16F870.
command : Execute programming command in non-interactive mode

As of today, the processor types supported by GPICD are:

*Processor Name*	*ICSP Supported*	*ICD Supported*
PIC16F87[0123467]	yes	yes
PIC16F87[3467]A	yes	yes
PIC16F8[34]	yes	no

The Shell-Command mode (a.k.a. non-interactive mode)

In this mode, a GPICD command is given as an argument when invoking gpicd-cmd from the OS shell.
The available non-interactive commands are:

*Command*	*Description*	*Examples*
`load hex-fileload cod-file`	Load iHEX8 or .COD file into program memory	`gpicd-cmd load blink.hexgpicd-cmd load blink.cod`
`load -d hex-file`	Load iHEX8 file into EEPROM data memory	`gpicd-cmd load -d config.hex`
`pwrite addr word`...	Write one or several word(s) to program memory from address `addr`	`gpicd-cmd pwrite 0 0x000000`
`pwrite -d addr word`...	Write one or several word(s) to EEPROM data memory from address `addr`	`gpicd-cmd pwrite -d 0 0x01 0x02`
`pread [-h]`	Read and display the whole program memory (option `-h` dumps program in iHEX8 format).	`gpicd-cmd pread -h`
`pread [-h] addr1[-addr2]`...	Read and display program memory segments (option `-h` dumps program in iHEX8 format).	`gpicd-cmd pread 0-3 0x2000-0x2007`
`pread -d [-h]`	Read and display the whole EEPROM data memory (option `-h` dumps data in iHEX8 format).	`gpicd-cmd pread -d`
`pread -d [-h] addr1[-addr2]`...	Read and display EEPROM data memory segments (option `-h` dumps data in iHEX8 format).	`gpicd-cmd pread -d 0x00 0x10-0x1F`

Screenshot: non-interactive gpicd-cmd operations

The Interactive Mode

In interactive mode, the command set listed in the previous table are still available. You can also use some additional ICD-oriented commands:

*Command*	*Description*
`reset`	Put the target processor in Reset state
`halt`	Halt the target program. Ignored if the target is not Running.
`run`	Start (after reset) or Resume (after halt or breakpoint) program execution. Ignored if the target is not Halted or Resetted.
`step`	Execute the next instruction and halt. Ignored if the target is not Halted.
`brk clear`	Clear the current breakpoint. Ignored if the target is not Halted.
`brk addr`	Put a breakpoint at address `addr`. Ignored if the target is not Halted.
`freeze on\|off`	Enable/disable peripheral freeze mode for ICD operation
`read` `addr`	Read file register at address `addr`
`write` `addr value`	Write a 8-bits `value` to file regiter at address `addr`
`verbose on\|off`	Change verbosity mode. When verbose mode is enabled, all ICSP/ICD operations that are performed to the target are displayed.
`config` `[kw [args]]`	Manage target configuration word (see the target configuration table below)
`icsp` `[field:value] ...`	Set and Show ICSP hardware interface configuration. The configuration settings are automatically saved in file .gpicd in the user's home directory. Available configuration fields are listed in the ICSP configuration table below.
`exit`	Exit the GPICD command line interpreter

Screenshot: gpicd-cmd interactive operations

The target configuration

The config command manages the target configuration word and some other programming options.

*Command*	*Description*
`config proc [type]`	If `type` is specified, select this processor type. Show current processor type. Available processor types are listed here.
`config debug [enable\|disable]`	Set and show debug mode (processor types PIC16F87x[A] only).
`config wrt [mode]`	Set and show flash program write mode. - For PIC16F87x : `mode` = { `enable`, `disable` } - For PIC16F87xA : `mode` = { `enable`, `half`,`quarter`,`256` }
`config cp` `[mode]`	Set and show Flash Program Memory Code Protection mode. - For PIC16F87[3467] : `mode` = { `enable`, `disable` } - For other processor types : `mode` = { `enable`, `half`,`256`, `disable` }
`config cpd` `[enable\|disable]`	Set and show EEPROM Data Memory Code Protection mode.
`config lvp` `[enable\|disable]`	Set and show Low-Voltage Programming mode (processor types PIC16F87x[A] only).
`config bor` `[enable\|disable]`	Set and show Brown-Out Reset mode.
`config pwrt` `[enable\|disable]`	Set and show Power-Up Reset Timer mode.
`config wdt` `[enable\|disable]`	Set and show Watchdog Timer mode.
`config fosc` `[rc\|hs\|xt\|lp]`	Set and show Oscillator mode.
`config read`	Read and show configuration word from target.
`config write`	Write configuration word to target.
`config erase` `[enable\|disable]`	Set and show 'Bulk-Erase before programming' option
`config download` `[enable\|disable]`	Set and show 'Download Debug Monitor' option

The hardware interface configuration

The icsp command manages the hardware interface configuration. This command accepts a list of parameters that specify a field and its value:
icsp field:value ...

Available configuration fields are listed in the table below.

*Field Name*	*Possible Values*	*Description*
`dev`	/dev/parportN	Parport device name. This device is implemented by the ppdev kernel module (which is Linux native)
`type`	GPICD AN589 Custom	Hardware interface type. GPICD and AN589 are two predefined types. Custom is a user-defined type, configurable using the other fields of this table.
`mclr`	D0 D1 D2 D3 D4 D5 D6 D7 ¹	Target reset. To be connected to the MCLR pin. ²
`vpp`	D0 D1 D2 D3 D4 D5 D6 D7 ¹	Vpp activation. To be connected to the circuitery that enabled Vpp in the MCLR pin. 2
`pgd_en`	NONE D0 D1 D2 D3 D4 D5 D6 D7 ¹	PGD data signal enable. 2
`pgd_out`	D0 D1 D2 D3 D4 D5 D6 D7 ¹	PGD data output. To be connected to the PGD/RB7 pin. 2
`pgd_in`	ERROR SELECT PE ACK BUSY ¹	PGD data input. To be connected to the PGD/RB7 pin. ²
`pgc_en`	NONE D0 D1 D2 D3 D4 D5 D6 D7 ¹	PGC clock signal enable. ²
`pgc_out`	D0 D1 D2 D3 D4 D5 D6 D7 ¹	PGC clock output. To be connected to the PGC/RB6 pin. ²
`activity`	NONE D0 D1 D2 D3 D4 D5 D6 D7 ¹	Activity LED. To be connected to a LED that flashes when the ICSP/ICD interface is working. ²

Note 1: Prefixing the signal value with a slash '/' indicates that the signal is inverted.
Note 2: This field is used by the Custom interface type only.

Examples of usage:
icsp dev:/dev/parport0 type:GPICD
icsp dev:/dev/parport1 type:Custom mclr:D3 vpp:D2 pgd_en:NONE pgd_out:/D0 pgd_in:ACK pgc_en:NONE pgc_out:/D1 activity:D0

http://gpicd.sourceforge.net