Commit 62dbb25d authored by Robert Sprowson's avatar Robert Sprowson Committed by ROOL
Browse files

Tone down ZPP warning, document developer modules

First added in July 2015, no longer provide ZeroPain with every development ROM since it could be seen as a cause for alarm to a new user, and is a useful diagnosis tool to old deck hands.
Move the documentation of ZeroPain to its new home in the BonusBin, and add some notes and a link to the docs of the other developer modules provided (DebugBttn, DebugTools).

Version 1.00. Tagged as 'ABRelease-1_00'
parent 5fb58ee0
...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete ...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete
and probably unstable in various ways. and probably unstable in various ways.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
CMOS RAM CMOS RAM
======== ========
......
...@@ -30,9 +30,6 @@ Copy ab_res:ReadMe/txt <ab_res$dir>.zip.ReadMe/txt ~cf~r~v ...@@ -30,9 +30,6 @@ Copy ab_res:ReadMe/txt <ab_res$dir>.zip.ReadMe/txt ~cf~r~v
| Compress the ROM image into the zip directory | Compress the ROM image into the zip directory
Do rompress -vZ --align=4096 <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos/img Do rompress -vZ --align=4096 <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos/img
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
Zero page relocation & ZeroPain Developer modules
=============================== =================
This build of RISC OS makes use of "zero page relocation", a change to the There are 3 modules provided to assist developers with debugging and diagnosing
some common software problems. They are
* DebugButtn
* DebugTools
* ZeroPain
Debug Button
============
This module intercepts Wimp service calls in order to add an extra
button (labelled "Debug") to Wimp error boxes where either:
a) the top bit of the error number is set, indicating an exception error
b) the flags word indicates it is a program report (ie unexpected error)
Clicking on this button will open a command window with a *Debug prompt
running in a simple environment - the current application cannot be replaced,
the exit handler tidies up the command window, and errors (such as those
caused by aborts from any comamnd line tool you use) do not cause an exit
from the command window. As usual with *Debug, you can press the Escape key
to resume the interrupted code.
DebugTools
==========
This module provides various low level commands to manipulate the environment.
While many are purely informational, beware that some of them are quite
dangerous and may crash the system if used inappropriately. For full details
of the commands visit
https://gitlab.riscosopen.org/RiscOS/Sources/Programmer/DebugTools/-/tree/master/Docs
ZeroPain
========
Since July 2015 builds of RISC OS 5 running on ARMv5 or later processors
have been available which make use of "zero page relocation", a change to the
standard memory map which moves the processor vectors and the kernel's "zero standard memory map which moves the processor vectors and the kernel's "zero
page" workspace away from address zero and up to the high end of the memory page" workspace away from address zero and up to the high end of the memory
map. This greatly increases the system's resilience to a common type of map.
This greatly increases the system's resilience to a common type of
software bug known as a "null pointer dereference", this comes in two forms: software bug known as a "null pointer dereference", this comes in two forms:
a) Reading a) Reading
...@@ -17,11 +59,9 @@ b) Writing ...@@ -17,11 +59,9 @@ b) Writing
the processor vectors, most likely this results in crashing the computer the processor vectors, most likely this results in crashing the computer
or similar knock on effects. or similar knock on effects.
Starting with RISC OS 5.24 the default state is running with the processor RISC OS 5.24 and later include a temporary measure where there is still
vectors and kernel's workspace moved away from zero page. But due to the a page of RAM left mapped in at the old address to allow buggy software to
large amount of buggy software out there as a temporary measure there is still continue to a limit. The access attributes are set such that:
a page of RAM left mapped in at the old address. The access attributes are
set such that:
a) Reading a) Reading
Is permitted in all processor modes (no change). Is permitted in all processor modes (no change).
...@@ -46,26 +86,25 @@ execute code. Some infrequently used instructions, such as LDRD, are also not ...@@ -46,26 +86,25 @@ execute code. Some infrequently used instructions, such as LDRD, are also not
dealt with. In these cases a data or prefetch abort will be raised as normal, dealt with. In these cases a data or prefetch abort will be raised as normal,
and the program will most likely terminate with an error. and the program will most likely terminate with an error.
Installation Installation
============ ------------
The recommended method of installation is to add the ZeroPain module to your The recommended method of installation is to add the ZeroPain module to your
Choices.Boot.PreDesk folder. This can be performed by using the boot merge Choices.Boot.PreDesk folder.
utility in Configure to merge in the !Boot structure that is provided here.
To ensure that the log file is clearly visible, the default log location is the To ensure that the log file is clearly visible, the default log location is the
file 'ZeroPain' in the root of your boot drive. However if desired you can file 'ZeroPain' in the root of your boot drive. However if desired you can
specify a different location for the file by editing the file !Boot.Choices. specify a different location by passing the desired log file name when the
Boot.PreDesk.!!ZeroPain.!Run. module is loaded, for example:
RMLoad ZeroPain ADFS::Foo.$.Bar.Log
The module is intended to be a temporary aid to be used until the dummy The module is intended to be a temporary aid to be used until the dummy
compatibility page of RAM at address zero is removed - it is not intended to compatibility page of RAM at address zero is removed - it is not intended to
be a long-term compatibility solution for running old or unmaintained software. be a long-term compatibility solution for running old or unmaintained software.
Using ZeroPain
Use --------------
===
There is little to know about using the module. As long as the module is There is little to know about using the module. As long as the module is
running, it will be monitoring the data abort vector and watching for attempts running, it will be monitoring the data abort vector and watching for attempts
...@@ -84,9 +123,8 @@ be reported to the author and added to the list of known problems ...@@ -84,9 +123,8 @@ be reported to the author and added to the list of known problems
ZeroPain will pause logging once the log file exceeds 1MB in size. Deleting the ZeroPain will pause logging once the log file exceeds 1MB in size. Deleting the
log will allow it to resume. log will allow it to resume.
Understanding log entries Understanding log entries
========================= -------------------------
Log entries produced by ZeroPain look like the following: Log entries produced by ZeroPain look like the following:
...@@ -204,9 +242,8 @@ boundary (the abort handler errs on the side of caution and avoids reading ...@@ -204,9 +242,8 @@ boundary (the abort handler errs on the side of caution and avoids reading
across page boundaries). However there should still be enough information to across page boundaries). However there should still be enough information to
allow the problem code to be identified. allow the problem code to be identified.
Annotated stack dumps Annotated stack dumps
===================== ---------------------
Some ZeroPain log entries will include an annotated stack dump after the Some ZeroPain log entries will include an annotated stack dump after the
disassembly. This stack dump can be critical in helping to identify the real disassembly. This stack dump can be critical in helping to identify the real
...@@ -228,11 +265,10 @@ summary entries that can be buffered at once. ...@@ -228,11 +265,10 @@ summary entries that can be buffered at once.
Developers or users who wish to understand more about the stack dump format and Developers or users who wish to understand more about the stack dump format and
the different annotations should consult this reference on the ROOL wiki: the different annotations should consult this reference on the ROOL wiki:
https://www.riscosopen.org/wiki/documentation/show/Debugger%20Annotated%20Exception%20Dumps https://www.riscosopen.org/wiki/documentation/show/Debugger%20Annotated%20Exception%20Dumps
Zero page workspace emulated by ZeroPain Zero page workspace emulated by ZeroPain
======================================== ----------------------------------------
When ZeroPain emulates a read from zero page, it will return the value 0 for When ZeroPain emulates a read from zero page, it will return the value 0 for
most locations. However, special handling is performed for the following most locations. However, special handling is performed for the following
...@@ -257,9 +293,8 @@ may limit our ability to make changes to the OS in future. ...@@ -257,9 +293,8 @@ may limit our ability to make changes to the OS in future.
&FF8 - 'DomainId'. May be used by some software to identify the current Wimp &FF8 - 'DomainId'. May be used by some software to identify the current Wimp
task. Use Wimp_ReadSysInfo instead. task. Use Wimp_ReadSysInfo instead.
High processor vectors High processor vectors
====================== ----------------------
Modern ARM CPUs support a feature known as 'high processor vectors', whereby Modern ARM CPUs support a feature known as 'high processor vectors', whereby
the processor vectors are moved from their old location at &0 to a new location the processor vectors are moved from their old location at &0 to a new location
...@@ -274,7 +309,7 @@ OS_PlatformFeatures 0 can be used to determine whether high processor vectors ...@@ -274,7 +309,7 @@ OS_PlatformFeatures 0 can be used to determine whether high processor vectors
are in use (flag returned in bit 20). Software which needs to interact with the are in use (flag returned in bit 20). Software which needs to interact with the
processor vectors directly should use this to determine their location. processor vectors directly should use this to determine their location.
https://www.riscosopen.org/wiki/documentation/show/OS_PlatformFeatures%200 https://www.riscosopen.org/wiki/documentation/show/OS_PlatformFeatures%200
The address of the processor vectors should not be used to infer the address of The address of the processor vectors should not be used to infer the address of
the zero page workspace, and vice-versa. the zero page workspace, and vice-versa.
......
...@@ -30,6 +30,7 @@ Copy <Install$Dir>.BonusBin <ab_res$dir>.zip.HardDisc4 ~cfr~v ...@@ -30,6 +30,7 @@ Copy <Install$Dir>.BonusBin <ab_res$dir>.zip.HardDisc4 ~cfr~v
| Copy the ReadMe for this build into the zip directory | Copy the ReadMe for this build into the zip directory
Copy ab_res:ReadMe/txt <ab_res$dir>.zip.ReadMe/txt ~cf~r~v Copy ab_res:ReadMe/txt <ab_res$dir>.zip.ReadMe/txt ~cf~r~v
Copy ab_res:Territories/txt <ab_res$dir>.zip.HardDisc4.Modules.Territories.ReadMe/txt ~cf~r~v Copy ab_res:Territories/txt <ab_res$dir>.zip.HardDisc4.Modules.Territories.ReadMe/txt ~cf~r~v
Copy ab_res:DeveloperModules/txt <ab_res$dir>.zip.HardDisc4.Modules.Developer.ReadMe/txt ~cf~r~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
| To specify an alternate log location, add it the end of the line below, e.g.
| 'X RMLoad <Obey$Dir>.ZeroPain ADFS::Foo.$.Bar.Log'
X RMLoad <Obey$Dir>.ZeroPain
...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete ...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete
and probably unstable in various ways. and probably unstable in various ways.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
How to install the ROM image How to install the ROM image
============================ ============================
......
...@@ -36,9 +36,6 @@ Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v ...@@ -36,9 +36,6 @@ Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v
| Copy the InstallHD4 script into the zip directory | Copy the InstallHD4 script into the zip directory
Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete ...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete
and probably unstable in various ways. and probably unstable in various ways.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
How to install the ROM image How to install the ROM image
============================ ============================
......
...@@ -36,9 +36,6 @@ Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v ...@@ -36,9 +36,6 @@ Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v
| Copy the InstallHD4 script into the zip directory | Copy the InstallHD4 script into the zip directory
Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete ...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete
and probably unstable in various ways. and probably unstable in various ways.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
The 'InstallHD4' script, and setting up a !Boot sequence The 'InstallHD4' script, and setting up a !Boot sequence
======================================================== ========================================================
......
...@@ -33,9 +33,6 @@ Copy <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos ~cf~r~v ...@@ -33,9 +33,6 @@ Copy <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos ~cf~r~v
| Copy the InstallHD4 script into the zip directory | Copy the InstallHD4 script into the zip directory
Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v Copy ab_res:InstallHD4 <ab_res$dir>.zip.InstallHD4 ~cf~r~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
...@@ -21,18 +21,4 @@ before committing it into the QSPI boot flash. Then, if something goes wrong ...@@ -21,18 +21,4 @@ before committing it into the QSPI boot flash. Then, if something goes wrong
it's possible to press the reset button and go back to the last flashed ROM. it's possible to press the reset button and go back to the last flashed ROM.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
-- RISC OS Open -- RISC OS Open
...@@ -37,9 +37,6 @@ Copy ab_res:SoftLoad <ab_res$dir>.zip.SoftLoad ~cf~r~v ...@@ -37,9 +37,6 @@ Copy ab_res:SoftLoad <ab_res$dir>.zip.SoftLoad ~cf~r~v
| Copy the ROM image into the zip directory | Copy the ROM image into the zip directory
Copy <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos ~cf~r~v Copy <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.zip.riscos ~cf~r~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
...@@ -10,18 +10,4 @@ softloading it should only be done if you are confident that you know what ...@@ -10,18 +10,4 @@ softloading it should only be done if you are confident that you know what
you are doing and have a good backup strategy in place! you are doing and have a good backup strategy in place!
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
-- RISC OS Open -- RISC OS Open
...@@ -36,9 +36,6 @@ Do rompress -vZps 4M <Build$Dir>.Images.<Build$ImageName> <ab_soft$dir>.riscos ...@@ -36,9 +36,6 @@ Do rompress -vZps 4M <Build$Dir>.Images.<Build$ImageName> <ab_soft$dir>.riscos
| Copy pre-EDID specific softload support | Copy pre-EDID specific softload support
Copy ab_res:Configure <ab_res$dir>.zip.soft.!Boot.Choices.Boot.PreDesk.Configure ~cfr~v Copy ab_res:Configure <ab_res$dir>.zip.soft.!Boot.Choices.Boot.PreDesk.Configure ~cfr~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete ...@@ -10,21 +10,6 @@ that you know what you are doing! It is likely to be functionally incomplete
and probably unstable in various ways. and probably unstable in various ways.
IMPORTANT
=========
This build of RISC OS utilises "zero page relocation", a change to the
standard memory map which is designed to increase the stability of the OS and
your software. However, there is a catch - a lot of existing software is buggy,
and this change will expose those bugs, causing the software to crash.
To help with the transition to having zero page relocation enabled by default,
a compatibility/logging module called 'ZeroPain' has been developed. See the
readme file in the ZeroPain folder for more information. It is recommended that
you install the module before you install this new ROM image, otherwise you may
have difficulty booting your system.
How to install the ROM image How to install the ROM image
============================ ============================
......
...@@ -33,9 +33,6 @@ Do rompress -vZ --align=4096 <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.z ...@@ -33,9 +33,6 @@ Do rompress -vZ --align=4096 <Build$Dir>.Images.<Build$ImageName> <ab_res$dir>.z
| Copy !SDCreate into the zip directory | Copy !SDCreate into the zip directory
Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v Copy <Install$Dir>.ABRelease.!SDCreate <ab_res$dir>.zip.!SDCreate ~cfr~v
| Copy ZeroPain into the zip directory
Copy ab_res:ZeroPain <ab_res$dir>.zip.ZeroPain ~cfr~v
| Set the zip directory as the current directory | Set the zip directory as the current directory
Dir <ab_res$dir>.zip Dir <ab_res$dir>.zip
......
/* (0.99) /* (1.00)
* *
* This file is automatically maintained by srccommit, do not edit manually. * This file is automatically maintained by srccommit, do not edit manually.
* *
*/ */
#define Module_MajorVersion_CMHG 0.99 #define Module_MajorVersion_CMHG 1.00
#define Module_MinorVersion_CMHG #define Module_MinorVersion_CMHG
#define Module_Date_CMHG 14 Mar 2020 #define Module_Date_CMHG 06 Jun 2020
#define Module_MajorVersion "0.99" #define Module_MajorVersion "1.00"
#define Module_Version 99 #define Module_Version 100
#define Module_MinorVersion "" #define Module_MinorVersion ""
#define Module_Date "14 Mar 2020" #define Module_Date "06 Jun 2020"
#define Module_ApplicationDate "14-Mar-20" #define Module_ApplicationDate "06-Jun-20"
#define Module_ComponentName "ABRelease" #define Module_ComponentName "ABRelease"
#define Module_FullVersion "0.99" #define Module_FullVersion "1.00"
#define Module_HelpVersion "0.99 (14 Mar 2020)" #define Module_HelpVersion "1.00 (06 Jun 2020)"
#define Module_LibraryVersionInfo "0:99" #define Module_LibraryVersionInfo "1:0"
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment