
	     PReg v1.00
	     ----------
	For VSOS 3.67 or higher
	2024-04-16 VLSI Solution

This programs can print contents of memory and registers. For all the
options available, run "PReg -h". This document describes the preg.db
and preg.dat formats used to show symbolic names.

The basic output format of PReg's register output looks as follows:

S:>PReg CF_IRAMWR
Y:0xfc2a=0x0000 CF_IRAMWR
          12    0   CF_IRAMWR_WRHDIS
        11:4   00   CF_IRAMWR_ST
         3:0    0   CF_IRAMWR_ENA
S:>

To be able to print all this symbolic data, PReg needs to have a database
of the available hardware registers. This database is in the file
S:SYSR/preg.dat. The documentation below presents how preg.dat has been
built in two steps:
1) Intermediate file preg.db is created from system include file vsrv.h.
2) Database file preg.dat is created from intermediate file preg.db.



preg.db, created with ./buildpregdb.pl < vsrv.h > preg.db
---------------------------------------------------------

buildpregdb.pl is a part of this package.

preg.db is built from vsrv.h, which is the system file for the VSDSP6 side
of the VSRV project. vsrv.h has to be created to adhere to the following
format.

Registers are initialized as follows:
---------
#define REG_NAME hex
where hex is a hexadecimal numvber in the range of 0xFC00 and 0xFFFF.
The number may not contain parenthesis or expressions.

If the register has less than 16 bits, its number of bits can be defined with
#define REG_NAME_REG_BITS x
where x is the number of bits.

Example:
#define CF_IRAMWR 0xFC2A
#define CF_IRAMWR_REG_BITS 13

Bitfields are initialized as follows:
---------
#define REG_NAME_BIT_NAME_B dec
where the prefix must be the register name the bit is going to be
attached to. If a bitfield consists of more than one bit, the lowest
bit must be named. The number may not contain parenthesis or expressions.

If there is an unused field, it should be named UNUSED. If there are more,
used UNUSED1, UNUSED2, etc.

Example:
#define CF_IRAMWR_WRHDIS_B      12
#define CF_IRAMWR_ST_B           4
#define CF_IRAMWR_ENA_B          0

The output file preg.db contains register and bitfield lines like the
following. The comments are not included in the file, they are here to
illustrate what the lines are presenting:

r FC2A CF_IRAMWR     // r = register at 0xFC2A, name CF_IRAMWR
w D CF_IRAMWR        // w = width, D = 0xd = 13, of register CF_IRAMWR
b C CF_IRAMWR_WRHDIS // b = bitfield at C = 0xc = 12, name CF_IRAMWR_WRHDIS
b 4 CF_IRAMWR_ST     // b = bitfield at 4, name CF_IRAMWR_ST
b 0 CF_IRAMWR_ENA    // b = bitfield at 0, name CF_IRAMWR_ENA



preg.dat, created with ./buildpregdat < preg.db > preg.dat
----------------------------------------------------------

buildpregdat.c that can be used to create buildpregdat using standard
ANSI-C 1989, is a part of this package.

buildpregdat combines collected data about registers, and combines bitfield
names and register widths with actual registers. It also combines some
non-regular register names with their corresponging bitfield names for some
legacy devices. For example, register UART0_STATUS is combined with bitfields
which don't have a prefix UART0_STATUS_ but UART_ST_ instead.

The output file preg.dat contains register and bitfield lines like the
following. The comments are not included in the file, they are here to
illustrate what the lines are presenting. Lines that start with an 'F'
are registers, lines starting with '0'-'9' or 'a'-'f' are bitfields of
the previous register. Registers are in ascending numerical order, bitfields
are in descending numerical order.

FC2ACF_IRAMWR       // Register CF_IRAMWR at 0xFC2A
c0CF_IRAMWR_WRHDIS  // from 0xc=12 to 0xc+0x0=12, name CD_IRAMWR_WRHDIS
47CF_IRAMWR_ST      // from 0xc= 7 to 0x7+0x4=11, name CD_IRAMWR_ST
03CF_IRAMWR_ENA     // from 0xc= 0 to 0x0+0x3= 3, name CD_IRAMWR_ENA



Version History:
2024-04-16 HH v1.00 - First release.
