*************************
Console command reference
*************************

There is a large number of console commands supported, but you only
need to be familiar with a small subset to make good use of the
Calypsi debugger.


.. index:: commands; essential

Essential commands
==================

.. table:: Essential commands
 :widths: 1 4
 :column-dividers: none single none

 +------------------+-------------------------------------------+
 |Command           |Description                                |
 +==================+===========================================+
 |``b`` *label*     |Set a breakpoint at given label            |
 +------------------+-------------------------------------------+
 |``run``           |Start the program                          |
 +------------------+-------------------------------------------+
 |``c``             |Continue execution                         |
 +------------------+-------------------------------------------+
 |``n``             |Step to next line, skipping over calls     |
 +------------------+-------------------------------------------+
 |``s``             |Step to next line, going into calls        |
 +------------------+-------------------------------------------+
 |``quit``          |Exit the debugger                          |
 +------------------+-------------------------------------------+
 |``Ctrl-c``        |Interrupt execution                        |
 +------------------+-------------------------------------------+


.. index:: commands; execution control, execution control

Execution control
=================

.. table:: Execution control
 :widths: 1 4
 :column-dividers: none single none

 +------------------+-------------------------------------------+
 |Command           |Description                                |
 +==================+===========================================+
 |``Ctrl-c``        |Interrupt execution                        |
 +------------------+-------------------------------------------+
 |``interrupt``     |Interrupt execution                        |
 +------------------+-------------------------------------------+
 |``r``             |Start the program                          |
 +------------------+-------------------------------------------+
 |``run``           |Start the program                          |
 +------------------+-------------------------------------------+
 |``s``             |Step to next source line, going into calls |
 +------------------+-------------------------------------------+
 |``step``          |Step to next source line, going into calls |
 +------------------+-------------------------------------------+
 |``si``            |Step at instruction level, going into      |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``stepi``         |Step at instruction level, going into      |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``n``             |Step to next source line, skipping over    |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``next``          |Step to next source line, skipping over    |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``ni``            |Step at instruction level, skipping over   |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``nexti``         |Step at instruction level, skipping over   |
 |                  |calls                                      |
 +------------------+-------------------------------------------+
 |``c``             |Continue execution                         |
 +------------------+-------------------------------------------+
 |``continue``      |Continue execution                         |
 +------------------+-------------------------------------------+
 |``kill``          |Abort execution                            |
 +------------------+-------------------------------------------+


.. index:: commands; breakpoints, breakpoint commands

Breakpoint commands
===================

Created breakpoints are given a numeric identity.
Conditional expressions and skip counts for breakpoints are supported.

.. table:: Breakpoint commands
 :widths: 1 3
 :column-dividers: none single none

 +-------------------------+-------------------------------------------+
 |Command                  |Description                                |
 +=========================+===========================================+
 |``info breakpoints``     |Display all breakpoints                    |
 +-------------------------+-------------------------------------------+
 |``b`` *label*            |Set a breakpoint at given label            |
 +-------------------------+-------------------------------------------+
 |``b`` *[file:]line*      |Set a breakpoint at source position        |
 +-------------------------+-------------------------------------------+
 |``b`` *address*          |Set a breakpoint at given address.         |
 |                         |The address must be preceded by a ``*``.   |
 |                         |A banked address can be entered as         |
 |                         |with ``bank:``, i.e. ``*2:0x5234``.        |
 +-------------------------+-------------------------------------------+
 |``break`` *arg*          |Same as ``b``                              |
 +-------------------------+-------------------------------------------+
 |``clear`` *label*        |Remove breakpoint at given label           |
 +-------------------------+-------------------------------------------+
 |``clear`` *[file:]line*  |Remove breakpoint at source position       |
 +-------------------------+-------------------------------------------+
 |``clear`` *address*      |Remove breakpoint at given address.        |
 +-------------------------+-------------------------------------------+
 |``delete`` *[n]*         |Remove breakpoint with given number, or    |
 |                         |all breakpoints if no argument             |
 +-------------------------+-------------------------------------------+
 |``enable`` *[n]*         |Enable breakpoint with given number, or    |
 |                         |all breakpoints if no argument             |
 +-------------------------+-------------------------------------------+
 |``disable`` *[n]*        |Disable breakpoint with given number, or   |
 |                         |all breakpoints if no argument             |
 +-------------------------+-------------------------------------------+
 |``condition`` *n* *expr* |Attach a conditional expression to given   |
 |                         |breakpoint                                 |
 +-------------------------+-------------------------------------------+


.. index:: commands; parameters, parameter commands

Parameters
==========

Parameters are provided to control behavior.

.. table:: Parameter commands
 :widths: 1 2
 :column-dividers: none single none

 +----------------------------+-------------------------------------------+
 |Command                     |Description                                |
 +============================+===========================================+
 |``set`` *parameter* *value* |Set a parameter                            |
 +----------------------------+-------------------------------------------+
 |``show`` *parameter*        |Display the value of a parameter           |
 +----------------------------+-------------------------------------------+

.. note::

   Many parameters are booleans, they can be set to true using ``on``
   or ``1``, and to false using ``off`` or ``0``.


.. index:: parameters, program context, context; program

.. table:: Parameters
 :widths: 1 2
 :column-dividers: none single none

 +-----------------------------+-------------------------------------------+
 |Parameter                    |Description                                |
 +=============================+===========================================+
 |``architecture``             |The target architecture                    |
 +-----------------------------+-------------------------------------------+
 |``breakpoint pending``       |Whether to allow pending breakpoints when  |
 |                             |a breakpoint cannot be set                 |
 +-----------------------------+-------------------------------------------+
 |``directories``              |Prepend the search path for source files   |
 +-----------------------------+-------------------------------------------+
 |``endian``                   |Target endian, normally derived from the   |
 |                             |debug image                                |
 +-----------------------------+-------------------------------------------+
 |``host-charset``             |The character set used by the host         |
 |                             |(normally UTF-8)                           |
 +-----------------------------+-------------------------------------------+
 |``language``                 |The source language being used             |
 +-----------------------------+-------------------------------------------+
 |``logging``                  |Controls logging to file                   |
 +-----------------------------+-------------------------------------------+
 |``lua errors``               |Controls how Lua errors are handled        |
 +-----------------------------+-------------------------------------------+
 |``mi-async``                 |Whether MI commands are processed or not   |
 |                             |when target is running                     |
 |                             |(Calypsi always try to processes MI        |
 |                             |commands, regardless of the state of the   |
 |                             |program being debugged)                    |
 +-----------------------------+-------------------------------------------+
 |``print sevenbit-strings``   |Controls how non-ASCII strings are         |
 |                             |displayed                                  |
 +-----------------------------+-------------------------------------------+
 |``prompt``                   |The current prompt text                    |
 +-----------------------------+-------------------------------------------+
 |``stop-line-count-before``   |Number of source lines to show before the  |
 |                             |current line when stopping                 |
 +-----------------------------+-------------------------------------------+
 |``stop-line-count-after``    |Number of source lines to show after the   |
 |                             |current line when stopping, plus 1 for the |
 |                             |current line itself                        |
 +-----------------------------+-------------------------------------------+
 |``target-charset``           |The character set used by the target       |
 |                             |(normally UTF-8)                           |
 +-----------------------------+-------------------------------------------+
 |``target-wide-charset``      |The wide character set used by the target  |
 |                             |(normally UTF-32)                          |
 +-----------------------------+-------------------------------------------+


The following parameters are recognized, but are not implemented and
purely exist for the benefit of various debugger front ends which may
issue them to initialize the debugger session.

.. table:: Other parameters
 :widths: 1 2
 :column-dividers: none single none

 +-----------------------------+-------------------------------------------+
 |Parameter                    |Description                                |
 +=============================+===========================================+
 |``auto-solib-add``           |Whether to load symbols automatically      |
 |                             |when shared libraries are being loaded     |
 +-----------------------------+-------------------------------------------+
 |``detach-on-fork``           |Only present for compatibility with        |
 |                             |debugger front ends                        |
 +-----------------------------+-------------------------------------------+
 |``inferior-tty``             |The terminal used by program being         |
 |                             |debugged                                   |
 +-----------------------------+-------------------------------------------+
 |``pagination``               |Whether pagination is enable or not        |
 |                             |(pagination is not currently supported)    |
 +-----------------------------+-------------------------------------------+
 |``non-stop``                 |Allow program threads to be examined while |
 |                             |other threads are running freely           |
 +-----------------------------+-------------------------------------------+
 |``print object``             |Whether an object's type should be based   |
 |                             |on vtable information                      |
 +-----------------------------+-------------------------------------------+
 |``set height``               |The height of a paginated display          |
 +-----------------------------+-------------------------------------------+
 |``solib-search-path``        |Search path for shared libraries           |
 +-----------------------------+-------------------------------------------+
 |``stop-on-solib-events``     |Whether to stop when shared libraries      |
 |                             |are being loaded or unloaded               |
 +-----------------------------+-------------------------------------------+
 |``target-async``             |Only for compatibility with older          |
 |                             |versions, use ``mi-async`` instead         |
 +-----------------------------+-------------------------------------------+


.. index:: commands; data manipulation, data manipulation commands

Data manipulation
=================

.. table:: Data manipulation
 :widths: 1 2
 :column-dividers: none single none

 +-------------------------------+-----------------------------------------------+
 |Command                        |Description                                    |
 +===============================+===============================================+
 |``info registers``             |Pretty print the register values               |
 +-------------------------------+-----------------------------------------------+
 |``p`` *expr*                   |Evaluate an expression                         |
 +-------------------------------+-----------------------------------------------+
 |``print`` *expr*               |Evaluate an expression (same as ``p``)         |
 +-------------------------------+-----------------------------------------------+
 |``disassemble`` *start*, *end* |Disassemble a region of memory                 |
 +-------------------------------+-----------------------------------------------+


.. index:: commands; files, file commands

File commands
=============

.. table:: File commands
 :widths: 1 3
 :column-dividers: none single none

 +------------------------------+-----------------------------------------------+
 |Command                       |Description                                    |
 +==============================+===============================================+
 |``exec-file`` *filepath*      |Specify the program to be debugged             |
 +------------------------------+-----------------------------------------------+
 |``file`` *filepath*           |Specify the program to be debugged             |
 |                              |(same as ``exec-file``)                        |
 +------------------------------+-----------------------------------------------+
 |``info sources``              |Show the program source files and how they are |
 |                              |mapped to real files on the file system        |
 +------------------------------+-----------------------------------------------+
 |``info source``               |Show the current program source file           |
 +------------------------------+-----------------------------------------------+


.. index:: commands; directory, directory commands

Directory context
=================

.. table:: Directory context
 :widths: 1 4
 :column-dividers: none single none

 +------------------------------+-----------------------------------------------+
 |Command                       |Description                                    |
 +==============================+===============================================+
 |``pwd``                       |Display current directory                      |
 +------------------------------+-----------------------------------------------+
 |``cd`` *path*                 |Set current directory                          |
 +------------------------------+-----------------------------------------------+
 |``directory``                 |Show the search path for source files          |
 +------------------------------+-----------------------------------------------+


.. index:: commands; threads, thread commands

Thread commands
===============

.. table:: Thread commands
 :widths: 1 4
 :column-dividers: none single none

 +------------------------------+-----------------------------------------------+
 |Command                       |Description                                    |
 +==============================+===============================================+
 |``info threads``              |Show the existing threads                      |
 +------------------------------+-----------------------------------------------+
 |``thread`` *n*                |Switch context to thread *n*                   |
 +------------------------------+-----------------------------------------------+


.. index:: commands; Lua, Lua commands

Lua commands
============

.. table:: Lua commands
 :widths: 1 2
 :column-dividers: none single none

 +------------------------------+-----------------------------------------------+
 |Command                       |Description                                    |
 +==============================+===============================================+
 |``source`` *filepath*         |Run a Lua script                               |
 +------------------------------+-----------------------------------------------+
 |``info lua instances``        |Show existing Lua instances                    |
 +------------------------------+-----------------------------------------------+
 |``lua remove instance`` *n*   |Remove a Lua instance                          |
 +------------------------------+-----------------------------------------------+

.. index:: commands; HP-41 modules, HP-41 module commands

HP-41 modules
=============

In addition to providing modules on the command line you can do it
using commands as well. This allows you to display and alter set of
plugged in modules without ending the debug session.

.. table:: HP-41 modules
 :widths: 1 3
 :column-dividers: none single none

 +-----------------------------+-----------------------------------------------+
 |Command                      |Description                                    |
 +=============================+===============================================+
 |``module insert`` *filepath* |Insert a plug-in module, ``.mod`` extension    |
 +-----------------------------+-----------------------------------------------+
 |``module list``              |Display the inserted modules                   |
 +-----------------------------+-----------------------------------------------+
 |``module remove`` *n*        |Remove the plug-in module that occupy the      |
 |                             |given page number                              |
 +-----------------------------+-----------------------------------------------+

.. note::

   You should turn the calculator off before altering the set of
   modules to avoid any potential strange behavior. This is because the
   calculator operating system as well as some modules, have code which
   configures the system for the current set of modules at power on.

.. index:: commands; miscellaneous, miscellaneou commands

Miscellaneous
=============

.. table:: Miscellaneous
 :widths: 1 2
 :column-dividers: none single none

 +------------------------------+-----------------------------------------------+
 |Command                       |Description                                    |
 +==============================+===============================================+
 |``show version``              |Show the current version of Calypsi            |
 |                              |debugger                                       |
 +------------------------------+-----------------------------------------------+
 |``quit``                      |Exit the debugger                              |
 +------------------------------+-----------------------------------------------+
 |``interpreter-exec mi`` *cmd* |Run an MI command                              |
 +------------------------------+-----------------------------------------------+
 |``source`` *filepath*         |Run a Lua script                               |
 +------------------------------+-----------------------------------------------+
 |``complete`` *text*           |Show completions to given command              |
 +------------------------------+-----------------------------------------------+
