ChorusOS man pages section 1CC: Host and Target Utilities

chls(1CC)

NAME

chls- ChorusOS Debug List tool

SYNOPSIS

chls

-lA

-la

actor ...

-lT

-lt

thread ...

-lr

-li

-le

-ll

nbline

-skip

nlines

-lM

-lR

-regs

-special-regs

-fp-regs

-all-regs

-i386-tss

addr

-i386-desc

cnt

addr

-lb

addr ...

-dump

format

addr ...

target ...

chls

-a

-b

-d

-flat

-dec

-hex

-format

-h

-l

-p

-r

-t

path

DESCRIPTION

chls is a host utility.

chls is a utility tool based on the Debug API to list the objects of the target. The tool has two modes:

A target oriented mode in which the options apply to one or several targets. In this mode, it provides most of the options of the cs tool and produces similar output. Additional options are provided for passive debugging analysis.
A second mode that allows you to look at all the objects and attributes of the Debug Object Tree.

The selection of the mode is based on the option that you use.

In the target mode, you specify a set of options eventually followed by one or several target names. If you don't specify a target name, chls searches and uses the first active target registered to the DebugServer. The targets that you specify must be registered to the Debug Server (see chadmin(1CC) and chserver). Refer to the cs(1CC) utility for a detailed explanation of the listing produced by the -lA, -la, -lt, -lM, -lr and -ll options.

OPTIONS

The following options are supported in the target mode which they activate:

-lA

Prints the list of running actors.

-la actor ...

Prints the microkernel resources belonging to the actors whose local identifiers actor follow the option.

-lT

Prints the list of running threads.

-lt thread ...

Prints the microkernel resources belonging to the threads whose local identifiers follow the option. For example:

-chls -lt ti1 ti2 ti3

prints the microkernel resources for threads identified by -ti1, ti2, ti3.

-lr

Prints the microkernel resources statistics.

-li

Prints target image description.

-le

Gives some information about exception handlers installed by the system.

-ll nbline

Prints the last nbline lines of the microkernel system log (see sysLog(2K)), if any.

-skip nlines

Skips the last nlines lines of the microkernel system log before listing the log.

-lM

Prints the list of microkernel modules

-lR

Prints the target RAM description

-regs

Prints the processor general registers. The output indicates the register name, the value in decimal and also in hexadecimal.

-special-regs

Prints the processor specific registers.

-fp-regs

Prints the processor floating point registers.

-all-regs

Prints all of the above three classes of registers.

-i386-tss addr ...

Dumps the content of i386 TSS. Addresses passed as parameter to this option represent the addresses of the TSS to be dumped. Addresses of i386 TSS are generally obtained by looking at the global descriptors.

-i386-desc cnt addr

Dumps the description of cnt i386 descriptors starting at address addr. The i386 has a global descriptor table whose address can be obtained by looking at the gdtr register. It also has a local descriptor table whose address is obtained by looking at the ldtr register.

-lb addr ...

Finds the system image component which owns the address.

-dump format addr ...

Dumps the memory area given a logical description of it (Refer to the extended description).

The following options are supported in the alternative mode:

-a: Lists all the attribute.s
-b: Lists only the attributes related to browsing information.
-d: Lists the attributes related to debug information.
-flat: Flat listing. Each object is printed with an absolute name. If attributes are printed, they are also listed with an absolute name.
-dec: Prints the integer attributes in decimal .form.
-hex: Prints the integer attributes in hexadecimal form.
-format: The sub-objects of a given object are listed according to the format string of the object.
-h: Help option. The usage of the tool is printed and the tool exits with the status code.
-l: Lists the objects.
-p: Lists the pre-defined attributes related to debug information.
-r: Recursive listing of the objects.
-t: Lists the targets registered in the DebugServe.

EXTENDED DESCRIPTION

chls allows you to dump the memory of the target. The memory dump is based on a logical description that you provide of the memory area. This logical description includes pointers so that linked lists and arbitrary complex data structures can be dumped.

The description is a string, each character of the string indicates the size of a basic entity to dump and how to dump it. When the entity is dumped, the address is incremented by the size of the entity. The description string contains the following characters:

1: Dump 1 byte in hexadecimal.
c: Dump 1 byte in character mode.
2: Dump 2 bytes in hexadecimal.
4: Dump 4 bytes in hexadecimal.
d: Dump 4 bytes in decimal.
8: Dump 8 bytes in hexadecimal.
[N]: Dump N bytes in character mode.
s: Read a 4-bytes pointer and dump the string pointed to by it.
l: Read a 4-bytes pointer and dump with the same memory description, the memory area pointed to by that pointer.

For example, the description string ls444 represents a structure composed of a pointer to the next element, a pointer to a string and three 32-bits integers. The use of the -dump requires some knowledge of the data structures to be dumped. It is possible to guess the structure by trying first to dump it as 32-bits integers, for example with 44444. Then, depending on values that are reported, and whether they look like possible pointers, you can switch the corresponding 4 into an s or an l.

EXAMPLES

To list the actors and the threads of a given target, use the following command:

chls --lA --lT mytarget

To list the objects that represent the actors in the Debug Object Tree, use the following command:

chls --flat --l targets/mytarget/actors

If you use the -format option instead of -flat option, you will obtain the same output as the -lA option. For example:

chls --format --l targets/mytarget/actors

ENVIRONMENT VARIABLES

The following environment variable is read by chls:

CHSERVER_HOST: The host name where the DebugServer is running.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving