AO-DBG(1)

✨ NAME ✨

Bestie, meet ao-dbg 💖, the manual page is AO-DBG(1) from the General Commands Manual 🎀

ao-dbg - hex debugger for cc1111 processors 🔥

✨ SYNOPSIS ✨

Here's every way you can call it 💅

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 ✨

Okay so ao-dbg hooks up to a cc1111 processor through either a suitable cc1111 board or a cp2103 usb to serial converter board, using the GPIO pins on that chip 🔌. It's giving compatible with the 8051 emulator from sdcc called s51, except it talks to the real chip instead of an emulation 🤯. With 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 built to match the 8051 emulator so they play nice with sdcdb 🧚 That's why they're all one letter long 💜

• -t cpu-type — the 8051 emulator can act like several different chips, but the real hardware can't, so this one gets ignored 🙈
• -X frequency — the emulator can pretend to run at any frequency, which the real hardware can't do, so this is ignored too 💀
• -c, -s, -S, -v, -V — all ignored 😴
• -r listen-port, -Z listen-port — switches the debugger from stdin/stdout to listening on a network port instead 🌐 Once a connection is made, it keeps using that port for command input and output. The debugger uses port 9756 and tries to connect before launching ao-dbg, so if ao-dbg is already listening on that port before sdcdb starts, sdcdb ends up talking to the existing ao-dbg instance 🦋 That's honestly super useful for debugging ao-dbg itself, ngl
• -p prompt — sets the command prompt to whatever string you give it 💬
• -P — sets the command prompt to a single NUL character, which is for sdcdb to use 🫶
• -h — should print a usage message, but right now it does nothing useful 😭
• -m — not in the original 8051 emulator, this one dumps every command and reply sent to and received from sdcdb 👀
• -T tty-device, --tty tty-device — picks which tty device the debugger uses to talk to the target. The special name BITBANG tells ao-dbg to use the cp2103 connection. Otherwise it should be a usb serial port connected to a suitable cc1111 debug node 🔌
• -D AltOS-device, --device AltOS-device — searches for a connected device. The argument has to be one of these forms:

TeleMetrum:2
TeleMetrum
2

Leave out the product name and the tool picks a suitable product. Leave out the serial number and it matches one of the available devices 💅

✨ COMMANDS ✨

Once it's started, ao-dbg connects to the cc1111 and then reads and runs commands, either from stdin or from the network connection to sdcdb 🌸

Unlike the command line, ao-dbg has built-in help for each command, via the help command 📚 Most commands come in a long form and a single-character short form. Below, the short form follows the long form after a comma 💜

• help, ? {command} — with no arguments, prints a list of available commands. With an argument, prints more detail about that specific command 📖
• quit, q — terminates the app 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. Heads up, most sprs show up in the global address space but some don't, so use this instead of dx to read them 👀
• dx [start] [end] — dumps external (global) memory from start to end, inclusive 🌍
• set, t <prefix> [start] {data ...} — stores to the memory space named by prefix, which is one of "xram", "rom", "iram", or "sfr". Stores bytes starting at start ✍️
• dump, d <prefix> [start] [end] — dumps from the memory space named by prefix, which is one of "xram", "rom", "iram" or "sfr". Dumps from start to end, inclusive 🗂️
• file [filename] — specifies an intel-format hex file (ihx) that holds the contents of the rom area loaded into the cc1111. This is used to answer requests to dump rom memory without grabbing them from the cc1111, which is slow 🐢
• pc, p {address} — if you give an address, it sets the program counter to that value. Otherwise, it displays the current program counter value 🧭
• break, b [address] — sets a breakpoint at the specified address using the cc1111's built-in hardware breakpoint support.

Heads up: that means no more than four breakpoints at once! You have to use a modified version of sdcdb that changes how program execution is controlled so it works within that limit.

• clear, c [address] — clears a breakpoint from the specified address 🧹
• run, r, go, g {start} {stop} — resumes execution of the program. If start is there, it begins at that address. Otherwise it keeps running from the current pc. If stop is there, a temporary breakpoint is set at that address, and it gets removed once execution hits it 🏃‍♀️
• next, n — steps one instruction. In the original s51 program this would skip over subroutines, but since sdcdb doesn't need that, it's not available here 🙅‍♀️
• step, s — steps one instruction 👣
• load, l [filename] — not implemented. It's supposed to load a hex file into flash, but you should use the ccload program instead 🚫
• halt, h — halts the processor. This is the only command you can send while the program is running. At other times it's ignored ✋
• reset, res — resets the processor. This pulls the reset pin low and re-enables debug mode. Check the cc1111 documentation to see exactly what it does 🔄
• status — dumps the cc1111 debug status register 🩺
• info, i breakpoints, b — lists the current breakpoints 📍
• info, i help, ? — lists the things you can get info on 💡
• stop — does absolutely nothing and is only here so it stays compatible with the original 8051 emulator 🤷‍♀️

✨ BOARD BRINGUP DEBUGGING ✨

So the original reason this program exists was to connect the source debugger to the hardware 🔧 But it's also a low-level hex debugger all on its own 🦋 You can poke every cc1111 peripheral directly from the ao-dbg command line, periodt 💅

Starting ao-dbg

First make sure the target cc1111 device and the in-between cp2103 or cc111 board are 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, can drive external LEDs 💡 To control them, set the Port 1 direction bits to make those pins outputs. 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 reference, an internal temperature sensor, or VDD/3 🌡️ To read one of these values, pick 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 set up one of the P0 pins for the A/D unit, program the ADCCFG register, setting the bits that match the pins you want:

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

To trigger a single conversion, ask the A/D unit to do an 'extra' conversion. That means one single conversion, not a whole sequence of them. 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 🫶

---

Stay iconic, bestie 💖 That's the whole ao-dbg page, straight from the source ao-dbg and filed under AO-DBG(1) 🌈✨