From: Keith Packard Date: Mon, 2 Mar 2009 07:12:31 +0000 (-0800) Subject: Add s51 manual. X-Git-Tag: 0.5~58^2~67 X-Git-Url: https://git.gag.com/?p=fw%2Faltos;a=commitdiff_plain;h=fdee231ed097a4348aee78fbd4aa92826b80de03;ds=sidebyside Add s51 manual. This documents (briefly) the s51 hex debugging interface program, including some simple commands to test the operation of the system interactively. Signed-off-by: Keith Packard --- diff --git a/s51/Makefile.am b/s51/Makefile.am index fa6fc692..6213750c 100644 --- a/s51/Makefile.am +++ b/s51/Makefile.am @@ -3,6 +3,8 @@ bin_PROGRAMS=s51 AM_CFLAGS=-I$(top_srcdir)/lib $(LIBUSB_CFLAGS) S51_LIBS=../lib/libcc.a +man_MANS = s51.1 + s51_DEPENDENCIES = $(S51_LIBS) s51_LDADD=$(S51_LIBS) $(LIBUSB_LIBS) diff --git a/s51/s51.1 b/s51/s51.1 new file mode 100644 index 00000000..f17f4810 --- /dev/null +++ b/s51/s51.1 @@ -0,0 +1,210 @@ +.\" +.\" Copyright © 2009 Keith Packard +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License along +.\" with this program; if not, write to the Free Software Foundation, Inc., +.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. +.\" +.\" +.TH S51 1 "s51" "" +.SH NAME +s51 \- hex debugger for cc1111 processors +.SH SYNOPSIS +.B "s51" +[\-t \fIcpu-type\fP] +[\-X \fIfrequency\fP] +[\-c] +[\-r \fIlisten-port\fP] +[\-Z \fIlisten-port\fP] +[\-s] +[\-S] +[\-p \fIprompt\fP] +[\-V] +[\-v] +[\-H] +[\-h] +[\-m] +.SH DESCRIPTION +.I s51 +connects to a cc1111 processor through a cp1203-based USB-to-serial +converter board, using the GPIO pins available on that chip. It provides an +interface compatible with the 8051 emulator of the same name (s51), but +communicating with the real chip instead of an emulation. Using a modified +version of the SDCC debugger (sdcdb), you can control program execution +on the target machine at source-level. + +.SH OPTIONS +The command line options are designed to be compatible with the 8051 +emulator so that it can be used with sdcdb. As such, they're all one letter +long. +.IP "\-t \fIcpu-type\fP" +The 8051 emulator can operate as one of several different chips. Oddly, the +real hardware cannot, so this option is ignored. +.IP "\-X \fIfrequency\fP" +Similarly, the emulator can pretend to run at an arbitrary frequency +which the real hardware cannot do. Ignored. +.IP "\-c" +.IP "\-s" +.IP "\-S" +.IP "\-v" +.IP "\-V" +All ignored. +.IP "\-r \fIlisten-port\fP, -Z \fIlisten-port\fP" +The emulator and sdcdb communicate through a network socket. This option +switches the debugger from communicating through stdin/stdout to listening +on a specific network port instead. Once a connection is made, the debugger +continues on, using that network port for command input and output. The +debugger uses port 9756, and attempts to connect before launching s51, so if +s51 is listening on this port before sdcdb is started, sdcdb will end up +talking to the existing s51 instance. That's often useful for debugging s51 +itself. +.IP "\-p \fIprompt\fP" +This sets the command prompt to the specified string. +.IP "\-P" +This sets the command prompt to a single NUL character. This is for use by +sdcdb. +.IP "\-h" +This should print a usage message, but does nothing useful currently. +.IP "\-m" +This option is not present in the original 8051 emulator, and causes s51 to +dump all commands and replies that are received from and sent to sdcdb. +.SH COMMANDS +Once started, s51 connects to the cc1111 via the CP2103 using libusb2 and +then reads and executes commands, either from stdin, or the nework +connection to sdcdb. +.PP +Unlike the command line, s51 contains built-in help for each of these +commands, via the 'help' command. Most of the commands are available in a +long form and a single character short form. Below, the short form follows +the long form after a comma. +.IP "help, ? {command}" +Without arguments, prints a list of available commands. With an argument +prints more detail about the specific command +.IP "quit, q" +Terminates the application, without changing the state of the target +processor. +.IP "di [start] [end]" +Dumps imem (256 bytes of "internal" memory) from start to end (inclusive). +.IP "ds [start] [end]" +Dumps sprs from start to end (inclusive). Note that while most sprs are +visible in the global address space, some are not, so use this command +instead of "dx" to read them. +.IP "dx [start] [end]" +Dump external (global) memory from start to end (inclusive). +.IP "set, t [start] {data ...}" +Store to the memory space specified by prefix where prefix is one of "xram", +"rom", "iram", or "sfr". Store bytes starting at start. +.IP "dump, d [start] [end]" +Dump from the memory space specified by prefix, where prefix is one of +"xram", "rom", "iram" or "sfr". Dumps from start to end (inclusive). +.IP "file [filename]" +Specifies an intel-format hex file (ihx) that contains the contents of the +rom area loaded into the cc1111. This is used to respond to requests to dump +rom memory contents without getting them from the cc1111 (which is slow). +.IP "pc, p {address}" +If the address argument is given, this sets the program counter to the +specified value. Otherwise, the current program counter value is displayed. +.IP "break, b [address]" +Sets a breakpoint at the specified address. This uses the built-in hardware +breakpoint support in the cc1111. As a result, it supports no more than four +breakpoints at once. You must therefore use a modified version of sdcdb which +changes how program execution is controlled to work within this limit. +.IP "clear, c [address]" +Clear a breakpoint from the specified address. +.IP "run, r, go, g {start} {stop}" +Resumes execution of the program. If the start argument is present, then it +begins at that address, otherwise it continues running at the current pc. If +a stop argument is present, then a temporary breakpoint is set at that +address. This temporary breakpoint will be removed when execution hits it. +.IP "next, n" +Step one instruction. In the original s51 program this would ignore +subroutines, but as sdcdb doesn't require this functionality, it's not +available here. +.IP "step, s" +Step one instruction. +.IP "load, l [filename]" +This is not implemented, but it is supposed to load a hex file into flash. +Use the ccload program instead. +.IP "halt, h" +Halt the processor. This is the only command which can be sent while the +program is running. It is ignored at other times. +.IP "reset, res" +Reset the processor. This pulls the reset pin low and re-enables debug mode. +Check the cc1111 documentation to see precisely what this does. +.IP "status" +This dumps the cc1111 debug status register. +.IP "info, i breakpoints, b" +List the current breakpoints. +.IP "info, i help, ?" +List the things you can get info on. +.IP "stop" +This doesn't do anything and is present only to retain compatibility with +the original 8051 emulator. +.SH "BOARD BRINGUP DEBUGGING" +.PP While the original purpose for this program was to connect the source +debugger with the hardware, it can also be used as a low-level hex debugger +all on its own. In particular, all of the cc1111 peripherals can be +manipulated directly from the s51 command line. +.IP "Starting s51" +If the CP2103 is plugged in, and the CC1111 is connected correctly, the +'s51' command itself should connect to the device without trouble. Note that +the CP2103 must have the GPIO pins configured correctly as well. +.IP +$ s51 +.br +Welcome to the non-simulated processor +.br +> status +.br + CPU halted +.br + Halted by debug command +.br +> +.IP "Turning on LEDs" +Two of the cc1111 GPIO pins, P1_0 and P1_1 are capable of driving external +LEDs. To control these, set the Port 1 direction bits to make these output +pins and then change the Port 1 data to set them high or low: +.IP +> set sfr 0xfe 0x02 # set P1DIR to 0x2 +.br +> set sfr 0x90 0x02 # set P1_1 to high +.br +> set sfr 0x90 0x00 # set P1_1 to low +.IP "Reading the A/D converters" +The six A/D converter inputs can each be connected to any of the P0 pins, +ground, the A/D voltage refernece, an internal temperature sensor or VDD/3. +To read one of these values, select an A/D converter to use then start the +conversion process. The cc1111 manual has the table for selecting the input +on page 144. +.IP +To configure one of the P0 pins for use by the A/D unit, we program the +ADCCFG register, setting the bits in that which match the pins desired: +.IP +> set sfr 0xf2 0x3f # enable all 6 A/D inputs +.IP +To trigger a single conversion, we as the A/D unit to perform an 'extra' +conversion, which means to do a single conversion not a whole sequence of +conversions. This is controlled by the ADCCON3 register at 0xB6: +.IP +> set sfr 0xb6 0xb2 # sample P0_2 using 12 bits of precision +.br +> ds 0xba 0xbb # dump the ADC data low and high regs +.br +> set sfr 0xb6 0xbe # sample internal temperature sensor +.br +> ds 0xba 0xbb # dump the ADC data low and high regs +.SH "SEE ALSO" +sdcdb(1), ccload(1) +.SH AUTHOR +Keith Packard