Provided by: altos_1.3.1-1_amd64 bug

NAME

       ao-dbg - hex debugger for cc1111 processors

SYNOPSIS

       ao-dbg  [-t  cpu-type] [-X frequency] [-c] [-r listen-port] [-Z listen-port] [-s] [-S] [-p
       prompt] [-V] [-v] [-H] [-h] [-m] [-T  tty-device]  [--tty  tty-device]  [-D  altos-device]
       [--device altos-device]

DESCRIPTION

       ao-dbg  connects  to a cc1111 processor through either a suitable cc1111 board or a cp2103
       usb to serial converter board, using the GPIO pins available on that chip. It provides  an
       interface  compatible  with the 8051 emulator from sdcc called 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.

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.

       -t cpu-type
              The 8051 emulator can operate as one of several different chips.  Oddly,  the  real
              hardware cannot, so this option is ignored.

       -X frequency
              Similarly, the emulator can pretend to run at an arbitrary frequency which the real
              hardware cannot do. Ignored.

       -c

       -s

       -S

       -v

       -V     All ignored.

       -r listen-port, -Z listen-port
              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 ao-dbg, so if ao-dbg is listening on this port
              before sdcdb is started, sdcdb will end up talking to the existing ao-dbg instance.
              That's often useful for debugging ao-dbg itself.

       -p prompt
              This sets the command prompt to the specified string.

       -P     This sets the command prompt to a single NUL character. This is for use by sdcdb.

       -h     This should print a usage message, but does nothing useful currently.

       -m     This option is not present in the original 8051 emulator, and causes ao-dbg to dump
              all commands and replies that are received from and sent to sdcdb.

       -T tty-device | --tty tty-device
              This  selects  which  tty  device  the debugger uses to communicate with the target
              device. The special name 'BITBANG' directs ao-dbg to  use  the  cp2103  connection,
              otherwise  this  should  be  a usb serial port connected to a suitable cc1111 debug
              node.

       -D AltOS-device | --device AltOS-device
              Search for a connected device. This requires an argument of one  of  the  following
              forms:

              TeleMetrum:2
              TeleMetrum
              2

              Leaving  out  the  product  name  will cause the tool to select a suitable product,
              leaving out the serial number will cause the tool to match  one  of  the  available
              devices.

COMMANDS

       Once  started,  ao-dbg connects to the cc1111 and then reads and executes commands, either
       from stdin, or the nework connection to sdcdb.

       Unlike the command line, ao-dbg 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.

       help, ? {command}
              Without arguments, prints a list of available commands.  With  an  argument  prints
              more detail about the specific command

       quit, q
              Terminates the application, without changing the state of the target processor.

       di [start] [end]
              Dumps imem (256 bytes of "internal" memory) from start to end (inclusive).

       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.

       dx [start] [end]
              Dump external (global) memory from start to end (inclusive).

       set, t <prefix> [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.

       dump, d <prefix> [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).

       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).

       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.

       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.

       clear, c [address]
              Clear a breakpoint from the specified address.

       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.

       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.

       step, s
              Step one instruction.

       load, l [filename]
              This is not implemented, but it is supposed to load a hex file into flash.  Use the
              ccload program instead.

       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.

       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.

       status This dumps the cc1111 debug status register.

       info, i breakpoints, b
              List the current breakpoints.

       info, i help, ?
              List the things you can get info on.

       stop   This doesn't do anything and is present  only  to  retain  compatibility  with  the
              original 8051 emulator.

BOARD BRINGUP DEBUGGING

       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 ao-dbg command line.

       Starting ao-dbg
              First  ensure  that the target cc1111 device and intermediate cp2103 or cc111 board
              are all hooked up correctly.

              $ ao-dbg
              Welcome to the non-simulated processor
              > status
                   CPU halted
                   Halted by debug command
              >

       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:

              > set sfr 0xfe 0x02 # set P1DIR to 0x2
              > set sfr 0x90 0x02 # set P1_1 to high
              > set sfr 0x90 0x00 # set P1_1 to low

       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.

              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:

              > set sfr 0xf2 0x3f # enable all 6 A/D inputs

              To trigger a single  conversion,  we  ask  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:

              > set sfr 0xb6 0xb2 # sample P0_2 using 12 bits of precision
              > ds 0xba 0xbb      # dump the ADC data low and high regs
              > set sfr 0xb6 0xbe # sample internal temperature sensor
              > ds 0xba 0xbb      # dump the ADC data low and high regs

SEE ALSO

       sdcdb(1), ccload(1)

AUTHOR

       Keith Packard

                                              ao-dbg                                    AO-DBG(1)