diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 1ab54b09..0d8be5ae 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -29,6 +29,7 @@ The full set of tests is only run for tagged releases. - cleanup tbrun setup, drop nexys4 and add nexys4d ([see blog](https://wfjm.github.io/blogs/w11/2019-07-27-nexys4-obituary.html)) - add ostest support for rsx11m-31_rk, rsx11m-40_rk and rsx11mp-30_rp oskits - Doxygen support now for V1.9.4 and without discontinued Tcl +- all actively used commands have now a man page ### New features ### Changes - tools changes diff --git a/tools/dox/README.md b/tools/dox/README.md index 8223feab..8b098286 100644 --- a/tools/dox/README.md +++ b/tools/dox/README.md @@ -8,7 +8,7 @@ covered by setup files contained in this directory. The doxygen generated source code view of the latest release is directly available from - [VHDL module list](https://www.retro11.de/doxy/w11/vhd/html/hierarchy.html) -- [sys_w11a_arty source](https://www.retro11.de/doxy/w11/vhd/html/sys__w11a__n3_8vhd_source.html) +- [sys_w11a_arty source](https://www.retro11.de/doxy/w11/vhd/html/sys__w11a__arty_8vhd_source.html) - [C++ class list](https://www.retro11.de/doxy/w11/cpp/html/hierarchy.html) To locally generate the html files use diff --git a/tools/man/README.md b/tools/man/README.md new file mode 100644 index 00000000..baf7370e --- /dev/null +++ b/tools/man/README.md @@ -0,0 +1,16 @@ +This directory tree contains *man pages** and is organized in + +| Directory | Content | +| --------- | ------- | +| [man1](man1) | man pages for section 1: Commands (Programs)| +| [man5](man5) | man pages for section 5: File formats and conventions| + +All actively used commands available in [tools/bin](../bin) have a _man_ page. +Only some legacy commands which will be removed in the near future are not +documented +``` + ticonv_pdpcp used from: ./tools/tcl/rw11/util.tcl: run_pdpcp + ticonv_rri used from: ./tools/tcl/rlink/util.tcl: run_rri + xilinx_tsim_xon used from: ./rtl/make_ise/generic_xflow.mk + xst_count_bels used from: ./rtl/make_ise/generic_xflow.mk +``` diff --git a/tools/man/man1/asm-11.1 b/tools/man/man1/asm-11.1 new file mode 100644 index 00000000..41eb0948 --- /dev/null +++ b/tools/man/man1/asm-11.1 @@ -0,0 +1,234 @@ +.\" -*- nroff -*- +.\" $Id: asm-11.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH ASM-11 1 2019-04-19 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +asm-11 \- simple assembler for MACRO-11 style PDP-11 code +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY asm-11 +.RI [ OPTION ]... +.I FILE... +. +.SY asm-11 +.B \-\-help +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +\fBasm-11\fP is a simple assembler for MACRO-11 style PDP-11 code that directly +generates a load module for an absolute loader. It is mainly used to compile +test bench code or other small bare-metal programs into a loadable format. + +\fBasm-11\fP accepts a subset of the MACRO-11 language and generates an +absolute binary in the formats +.RS 2 +.PD 0 +.IP "-" 2 +\fBlda-11\fP(5): the DEC standard absolute binary format, can be directly +used with the paper tape loader. +Activated with the \fB\-\-lda\fP or \fB\-\-olda\fP options. +.IP "-" +\fBcof-11\fP(5): a custom format that contains the full symbol table and the +absolute binary. Very useful when access to the symbol table is needed, for +example in test bench codes. +Activated with the \fB\-\-cof\fP or \fB\-\-ocof\fP options. +.IP "-" +\fBlsm-11\fP(5): very simple word wise 'addr:data' memory dump. Useful when +used in combination with some w11 tools, e.g. \fBdasm-11\fP. +Activated with the \fB\-\-lsm\fP or \fB\-\-olsm\fP options. +.PD +.RE +.PP + +\fBasm-11\fP can create a listing in a format very close to that generated by +the MACRO-11 assembler. +Activated with the \fB\-\-lst\fP or \fB\-\-olst\fP options. + +\fBasm-11\fP provides only the most basic assembler directives + +.EX + .ascii stores ascii string + .asciz stores ascii string with trailing zero + .asect absolute program section (current default, dummy imp) + .blkb allocate bytes of storage + .blkw allocate words of storage + .byte store bytes of data + .end end of source + .even ensure word aligment + .include include another source file + .odd align to odd byte address + .word store words of data +.EE + +and thus neither macro, nor conditional assembly, nor psect support. +. +.\" ------------------------------------------------------------------ +.SH OPTIONS +. +.\" ---------------------------------------------- +.IP "\fB\-I\fI path\fR" +adds path to the .include search path. +. +.\" ---------------------------------------------- +.IP "\fB\-\-lst\fR" +create listing with a default file name built from the basename of the first +\fIFILE\fP plus a \fI.lst\fP extension. +If \fIFILE\fP is '-' the output is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-\-olst=\fIfnam\fR" +create a listing and write it to file \fIfnam\fR. +If \fIfnam\fP is '-' the listing is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-\-lda\fR" +create absolute loader output in \fBlda-11\fP(5) format with a default file name +built from the basename of the first \fIFILE\fP plus a \fI.lda\fP extension. +If \fIFILE\fP is '-' the output is written to \fIstdout\fP. + +. +.\" ---------------------------------------------- +.IP "\fB\-\-olda=\fIfnam\fR" +create absolute loader output in \fBlda-11\fP(5) format and write it to +file \fIfnam\fR. +If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-\-cof\fR" +create compound output in \fBcof-11\fP(5) format with a default file name +built from the basename of the first \fIFILE\fP plus a \fI.cof\fP extension. +If \fIFILE\fP is '-' the output is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-\-ocof=\fIfnam\fR" +create compound output in \fBcof-11\fP(5) format and write it to file \fIfnam\fR. +If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP. +If both \fB\-\-olst=-\fP and \fB\-\-ocof=-\fP and are specified, the listing +output comes first, followed by the compound output. +. +.\" ---------------------------------------------- +.IP "\fB\-\-lsm\fR" +create lsmem style memory dump in \fBlsm-11\fP(5) format with a default file +name built from the basename of the first \fIFILE\fP plus a \fI.lsm\fP extension. +If \fIFILE\fP is '-' the output is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-\-olsm=\fIfnam\fR" +create lsmem style memory dump in \fBlsm-11\fP(5) format and write it to +file \fIfnam\fR. +If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP. +. +.\" ---------------------------------------------- +.IP "\fB\-help\fR" +print full help text and exit. +. +.\" ------------------------------------------------------------------ +.SH OPTIONS FOR DEBUG +. +.\" ---------------------------------------------- +.IP "\fB\-\-tpass1\fR" +trace line context in pass 1. +. +.\" ---------------------------------------------- +.IP "\fB\-\-tpass2\fR" +trace line context in pass 2. +. +.\" ---------------------------------------------- +.IP "\fB\-\-dsym1\fR" +dump psect and ust tables after pass 1. +. +.\" ---------------------------------------------- +.IP "\fB\-\-dsym2\fR" +dump psect and ust tables after pass 2. +. +.\" ---------------------------------------------- +.IP "\fB\-\-ttoken\fR" +trace tokenizer. +. +.\" ---------------------------------------------- +.IP "\fB\-\-tparse\fR" +trace parser. +. +.\" ---------------------------------------------- +.IP "\fB\-\-temit\fR" +trace code emit. +. +.\" ---------------------------------------------- +.IP "\fB\-\-tout\fR" +trace output file write. +. +.\" ------------------------------------------------------------------ +.SH EXIT STATUS +If files can't be opened or an assembler error is detected an +exit status 1 is returned. + +.\" ------------------------------------------------------------------ +.SH EXAMPLES +.\" -------------------------------------------------------- +.SS Direct usage +. +.IP "\fBasm-11 -lst -lda test.mac\fR" 4 +Compiles \fItest.mac\fP and creates listing file \fItest.lst\fP and +absolute loader file \fItest.lda\fP. +. +.IP "\fBasm-11 \-\-olst=\- \-\-ocof=\- \-\fR" +Reads the input from \fIstdin\fP and writes a listing followed by a +compound output to \fIstdout\fP. This usage style is convenient when +integrating \fBasm-11\fP with other tools. +.\" -------------------------------------------------------- +.SS Embedded usage +. +.IP "\fBfrom ti_w11 command line\fR" 4 +The \fB-e\fP option of the \fBti_w11\fP command uses \fBasm-11\fP to compile a +\fI.mac\fP source file and load the binary in either a +w11 design on an FGPA or a test bench. Example +.EX + ti_w11 -n4d -e $RETROBASE/tools/mcode/dl11/dl11echo.mac +.EE +. +.IP "\fBfrom ti_w11 command prompt\fR" +The \fBlsasm\fP subcommand of a CPU object uses \fBasm-11\fP to compile a +\fI.mac\fP source file, load the binary, and capture the listing and +the symbol table. + +.EX + cpu0 ldasm -file "test.mac" -sym sym -lst lst + cpu0 cp stapc $sym(...end) +.EE + +compiles \fItest.mac\fP and leaves the listing in Tcl variable \fIsym\fP and +the symbol table in Tcl array \fIlst\fP. If the code specified a start address +via a \fI.end\fP directive it can be accessed via \fI$sym(...end)\fP. + +.EX + cpu0 ldasm -lst lst -sym sym { + ... MACRO-11 code ... + } +.EE + +compiles and loads a code snippet embedded in the Tcl script. +Again, the symbol table in Tcl array \fIlst\fP. +This usage style is heavily used in test benches. +The direct and easy access to the symbol table allows a very tight +interaction between the verification code in the test bench and the +code executed on the target system. +. +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR asm-11_expect (1), +.BR ti_w11 (1), +.BR dasm-11 (1), +.BR lda-11 (5), +.BR cof-11 (5), +.BR lsm-11 (5) + +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man1/ip_inspect.1 b/tools/man/man1/ip_inspect.1 new file mode 100644 index 00000000..cc4d8b89 --- /dev/null +++ b/tools/man/man1/ip_inspect.1 @@ -0,0 +1,49 @@ +.\" -*- nroff -*- +.\" $Id: ip_inspect.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH IP_INSPECT 2018-12-18 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +ip_inspect \- inquire individual network object properties +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY ip_inspect defeif +.SY ip_inspect defroute +.SY ip_inspect addr4 +.I LINK +addrm | addr | mask | bcast +.SY ip_inspect help +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION + +\fB\ip_inspect\fP inquire individual network object properties from \fBip\fP(1). + +Currently implemented properties are: +.IP "\fBip_inspect defeif\fR" +returns default ethernet interface (e.g. "enp2s0") +.\" ---------------------------------------------- +.IP "\fBip_inspect defroute\fR" +returns default route +.\" ---------------------------------------------- +.IP "\fBip_inspect addr4 \fILINK\fP addrm\fR" +returns ip4 address/mask for interface \fILINK\fP (e.g. "192.168.178.20/24") +.\" ---------------------------------------------- +.IP "\fBip_inspect addr4 \fILINK\fP addr\fR" +returns ip4 address for interface \fILINK\fP (e.g. "192.168.178.20") +.\" ---------------------------------------------- +.IP "\fBip_inspect addr4 \fILINK\fP mask\fR" +returns ip4 address mask for interface \fILINK\fP (e.g. "255.255.255.0") +.\" ---------------------------------------------- +.IP "\fBip_inspect addr4 \fILINK\fP bcast\fR" +returns ip4 broadcast address for interface \fILINK\fP (e.g. "192.168.178.255") +.\" ------------------------------------------------------------------ +. +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man1/makeise.1 b/tools/man/man1/makeise.1 new file mode 100644 index 00000000..391cd7a9 --- /dev/null +++ b/tools/man/man1/makeise.1 @@ -0,0 +1,27 @@ +.\" -*- nroff -*- +.\" $Id: makeise.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH MAKEISE 1 2019-06-29 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +makeise \- execute make with ISE +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY makeise +.I ARGLIST +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +Shortcut for \fBmake -f Makefile.ise\fP. Convenient in project directories +that contain a \fIMakefile\fP for \fBvivado\fP builds and a +\fIMakefile.ise\fP for \fBISE\fP builds. All arguments are forwarded. +. +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man1/telnet_wrapper.1 b/tools/man/man1/telnet_wrapper.1 new file mode 100644 index 00000000..bfda822c --- /dev/null +++ b/tools/man/man1/telnet_wrapper.1 @@ -0,0 +1,33 @@ +.\" -*- nroff -*- +.\" $Id: telnet_wrapper.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH TELNET_WRAPPER 1 2017-05-25 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +telnet_wrapper \- handle telnet connection in a console_starter window +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY telnet_wrapper +.I HOST +.I PORT +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +Used by \fBconsole_starter\fP to establish the \fBtelnet\fP(1) connection +to either a \fBti_w11\fP backend or SimH simulator running on host \fIHOST\fP +and port \fIPORT\fP. +. +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR console_starter (1) +.BR ti_w11 (1) + +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man1/tmuconv.1 b/tools/man/man1/tmuconv.1 new file mode 100644 index 00000000..1e3334d8 --- /dev/null +++ b/tools/man/man1/tmuconv.1 @@ -0,0 +1,101 @@ +.\" -*- nroff -*- +.\" $Id: tmuconv.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH TMUCONV 1 2010-10-22 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +tmuconv \- convert w11a tmu output into human readable format +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY tmuconv +.OP \-dump +.OP \-cdump +.OP \-t_id +.OP \-t_ru +.OP \-t_em +.OP \-t_ib +.I FILE +. +.SY tmuconv +.B \-\-help +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +Converts the output of the \fBw11a\fR trace and monitoring unit (tmu) +into a human readable format. +. +.\" ------------------------------------------------------------------ +.SH OPTIONS +. +.\" ---------------------------------------------- +.IP "\fB\-dump\fR" +dump all information +. +.\" ---------------------------------------------- +.IP "\fB\-cdump\fR" +dump only changes relative to previous cycle +. +.\" ---------------------------------------------- +.IP "\fB\-t_id\fR" +trace instruction decodes +. +.\" ---------------------------------------------- +.IP "\fB\-t_ru\fR" +trace register updates +. +.\" ---------------------------------------------- +.IP "\fB\-t_em\fR" +trace em transactions (external memory bus) +. +.\" ---------------------------------------------- +.IP "\fB\-t_ib\fR" +trace ib transactions (ibus cycles) +. +.\" ---------------------------------------------- +.IP "\fB\-help\fR" +print full help text and exit. +. +.\" ------------------------------------------------------------------ +.SH EXAMPLES +.IP "\fBtmuconv --t_id --t_em --t_ib tmu_ofile\fR" 4 +Produces an output with all instruction decodes and external memory interface +and ibus transactions. The execution of a 'bisb #4,4(r4)' instruction which +accesses the output CSR of a DL11 interface will look like + +.EX + 429 id 002002 000340 152764 bisb #nnn,nnn(r4) (5) + 431 em r 01 00002004 000004 0100 (1) + 433 em r 11 00002006 000004 0100 (1) + 435 em r 01 00177564 cancel 1100 (1) + 436 ib -- rm01 177564 000200 1 (0) to.csr + 439 ib -- wm01 177564 000204 1 (0) to.csr +.EE + +and shows the canceled em access and the ibus read-modify-write. + +.IP "\fBtmuconv --t_id --t_em --t_ib --t_ru tmu_ofile\fR" 4 +Like above, in addition, also all register updates are shown. The execution +of a 'cmp (r2),(r4)+' where r2 points to the psw will look like + +.EX + 934 id 003014 000011 021224 cmp (r2),(r4)+ (9) + 936 em r 11 00177776 cancel 1000 (1) + 937 ib -- r 11 177776 000011 1 (0) psw + 939 ru 0 04 005676 003036 003040 177776 005700 005676*005570 r04 + 940 em r 11 00005674 000011 0101 (1) +.EE + + +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR ti_rri (1) + +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man1/xilinx_vhdl_memcolltype_fix.1 b/tools/man/man1/xilinx_vhdl_memcolltype_fix.1 new file mode 100644 index 00000000..a3262bcd --- /dev/null +++ b/tools/man/man1/xilinx_vhdl_memcolltype_fix.1 @@ -0,0 +1,45 @@ +.\" -*- nroff -*- +.\" $Id: xilinx_vhdl_memcolltype_fix.1 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH XILINX_VHDL_MEMCOLLTYPE_FIX 1 2007-10-28 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +xilinx_vhdl_memcolltype_fix \- cleanup faulty VHDL in Xilinx libraries +.\" ------------------------------------------------------------------ +.SH SYNOPSIS +. +.SY xilinx_vhdl_memcolltype_fix +.YS +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +The Xilinx \fIsimprim\fP and \fIunisim\fP libraries contain code like + +.EX + variable Write_A_Write_B : memory_collision_type := Write_A_Write_B; + variable Read_A_Write_B : memory_collision_type := Read_A_Write_B; + variable Write_A_Read_B : memory_collision_type := Write_A_Read_B; + variable Write_B_Write_A : memory_collision_type := Write_B_Write_A; + variable Read_B_Write_A : memory_collision_type := Read_B_Write_A; + variable Write_B_Read_A : memory_collision_type := Write_B_Read_A; +.EE + +These are a self-referential init and causes \fBghdl\fP compilation errors. + +This script scans all \fI.vhd\fP files in the current working directory, +and removes lines like this. Used by \fBxise_ghdl_simprim\fP, +\fBxise_ghdl_unisim\fP, and \fBxviv_ghdl_unisim\fP. + +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR xise_ghdl_simprim (1), +.BR xise_ghdl_unisim (1), +.BR xviv_ghdl_unisim (1) + +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man5/cof-11.5 b/tools/man/man5/cof-11.5 new file mode 100644 index 00000000..f6b941b1 --- /dev/null +++ b/tools/man/man5/cof-11.5 @@ -0,0 +1,86 @@ +.\" -*- nroff -*- +.\" $Id: cof-11.5 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH COF-11 5 2022-05-13 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +cof-11 \- compound output format for absolute loader images +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +\fBcof-11\fP files contain both the full symbol table and the absolute binary +of an \fBasm-11\fP compilation in an easy to process text format. +It is usually used to transfer the compilation result when \fBasm-11\fP is +embedded. +A \fBcof-11\fP has a symbol section with a list of name-value pairs and +a data section with a list of word or byte blocks. Each block has a +word/byte indicator, the starting address, and a blank-separated list of values. +All numerical values are in octal format. + +.EX + sym { + => + ... + } + dat { + w { + ... + } + b { + ... + } + ... + } +.EE + +The symbol table also contains local labels in the form +.EX + incnum => 001154 + incnum:1$ => 001160 + incnum:100$ => 001200 +.EE +with the normal label followed by a ':' and the local label. + +.\" ------------------------------------------------------------------ +.SH EXAMPLES +.IP "\fBasm-11 -cof lp11write.mac\fR" 4 +produces a \fBcof-11\fP file like (shortened for brevity) + +.EX + sym { + ...end => 001000 + bend => 001310 + bnum => 001202 + btxt => 001206 + incnum => 001154 + incnum:1$ => 001160 + incnum:100$ => 001200 + perr => 001150 + ... + dat { + w 000004 { + 000006 000000 000012 000000 000016 000000 000022 000000 000026 + 000032 000000 000036 000000 + } + w 000240 { + 000242 000000 000246 000000 000252 000000 + } + ... + b 001202 { + 060 060 060 060 072 040 101 102 103 104 105 106 107 110 111 112 + ... + } + } +.EE +. +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR asm-11 (1) +. +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man5/lda-11.5 b/tools/man/man5/lda-11.5 new file mode 100644 index 00000000..c2b81255 --- /dev/null +++ b/tools/man/man5/lda-11.5 @@ -0,0 +1,76 @@ +.\" -*- nroff -*- +.\" $Id: lda-11.5 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH LDA-11 5 2022-05-13 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +lda-11 \- absolute loader paper tape format +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +\fBlda-11\fP files contain an absolute binary executable for a PDP-11 system. +They were initially defined for usage with paper tapes, see +.EX + Paper Tape Software Programming Handbook DEC-11-OOPB-D Mar 1971 + Paper Tape Software Handbook DEC-11-XPTSA-B-D Apr 1976 +.EE +and later used in the disk-based \fBxxdp\fP system. DEC RT-11 and RSX tools +also supported this file format. + +An \fBlda-11\fP file contains one or more blocks of the format + +.EX + 0 001 start frame + 1 000 null frame + 2 xxx byte count low + 3 xxx byte count hight + 4 yyy load address low + 5 yyy load address high + ... data + zzz block checksum +.EE + +and the properties +. +.RS 0 +.PD 0 +.IP "-" 2 +the byte count is the total number of bytes in a block, excluding the checksum +but including the 6 header frames. +.IP "-" +the checksum is the 2-complement of the sum of the whole block, +including the 6 byte header +.IP "-" +if the byte count is 6: +.RS 2 +.PD 0 +.IP "-" 2 +if the load address is even, the loader will transfer control to that address +.IP "-" +if the load address is odd, the loader stops the CPU with a HALT +.PD +.RE +.PP +. +.PD +.RE +.PP +. +.\" ------------------------------------------------------------------ +.SH "NOTES" +\fBlda-11\fP files can be created with \fBasm-11\fP, inspected with +\fBldadump\fP, and loaded into a system with \fBti_w11\fP. +. +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR asm-11 (1), +.BR ldadump (1), +.BR ti_w11 (1) +. +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller diff --git a/tools/man/man5/lsm-11.5 b/tools/man/man5/lsm-11.5 new file mode 100644 index 00000000..53c026c5 --- /dev/null +++ b/tools/man/man5/lsm-11.5 @@ -0,0 +1,40 @@ +.\" -*- nroff -*- +.\" $Id: lsm-11.5 1237 2022-05-15 07:51:47Z mueller $ +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" Copyright 2022- by Walter F.J. Mueller +.\" +.\" ------------------------------------------------------------------ +. +.TH LSM-11 5 2022-05-13 "Retro Project" "Retro Project Manual" +.\" ------------------------------------------------------------------ +.SH NAME +lsm-11 \- lsmem style memory dump format +. +.\" ------------------------------------------------------------------ +.SH DESCRIPTION +\fBlsm-11\fP files contain a 16 bit memory dump in the format produced +by the \fIlsmem\fP subcommand. It is simply a list with one \fIaddr:data\fP +pair per line, both \fIaddr\fP and \fIdata\fP are given as 16 bit octal numbers. +Like for example +.EX +000000 : 012700 +000002 : 000026 +000004 : 105710 +000006 : 001406 +000010 : 105737 +000012 : 177564 +.EE +. +.\" ------------------------------------------------------------------ +.SH "NOTES" +\fBlsm-11\fP files can be created with \fBasm-11\fP. +\fBlda-11\fP files can be converted into \fBlsm-11\fP format with \fBldadump\fP. +. +.\" ------------------------------------------------------------------ +.SH "SEE ALSO" +.BR asm-11 (1), +.BR ldadump (1) +. +.\" ------------------------------------------------------------------ +.SH AUTHOR +Walter F.J. Mueller