DJGPP documentation updates

[Ozkan Sezer ([e-mail]) [via [e-mail]]]

Hello,
I figured out that you are one of the last contributors to the DJGPP
project. I would like to ask, what is the state of the DJGPP project?
It is still developed or it is not active anymore?
I have some changes for DJGPP documentation and if the DJGPP project is
still active I can send you documentation file diffs. Please let me know
if you (or somebody else) would like to see them.

This must be asked / discussed on the djgpp mailing list: Added to CC.

[DJ Delorie]

what is the state of the DJGPP project?

IMHO DJGPP is in "very long term stable maintenance mode". I mean, it's
not like MS-DOS is still changing, right?

It is still developed or it is not active anymore?

There are a few who continue to work on it, mostly maintaining ports and
builds. Activity is very low but hasn't stopped yet.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Wed, 14 Feb 2024 03:27:00 +0300

Hello,
I figured out that you are one of the last contributors to the DJGPP
project. I would like to ask, what is the state of the DJGPP project?
It is still developed or it is not active anymore?
I have some changes for DJGPP documentation and if the DJGPP project is
still active I can send you documentation file diffs. Please let me know
if you (or somebody else) would like to see them.

This must be asked / discussed on the djgpp mailing list: Added to CC.

Can you tell what kind of documentation changes you are talking about?

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sat, 17 Feb 2024 16:52:10 +0100

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

Date: Wed, 14 Feb 2024 03:27:00 +0300

Hello,
I figured out that you are one of the last contributors to the DJGPP
project. I would like to ask, what is the state of the DJGPP project?
It is still developed or it is not active anymore?
I have some changes for DJGPP documentation and if the DJGPP project is
still active I can send you documentation file diffs. Please let me know
if you (or somebody else) would like to see them.

This must be asked / discussed on the djgpp mailing list: Added to CC.

Can you tell what kind of documentation changes you are talking about?

--- src/libc/dpmi/api/d0401.txh
+++ src/libc/dpmi/api/d0401.txh
@@ -14,8 +14,8 @@ Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation. Also see
-DPMI function AX = 0x0401 (DPMI 1.0 only). Not supported by CWSDPMI and
-Windows.
+DPMI function AX = 0x0401 (DPMI 1.0 only). Supported by CWSDPMI v5+,
+but not by Windows.

Such changes are, of course, welcome. So how about posting them here,
and let people review and comment? Then we can install the parts that
look useful.

Thanks.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sat, 17 Feb 2024 22:55:43 +0100

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
Such changes are, of course, welcome. So how about posting them here,
and let people review and comment? Then we can install the parts that
look useful.
Thanks.

Ok, here is another simple change for web documentation. Text
"Capability not supported" is rendered above the HTML table. I have not
--- https://www.delorie.com/djgpp/doc/dpmi/api/310508.html
+++ https://www.delorie.com/djgpp/doc/dpmi/api/310508.html
@@ -53,8 +53,8 @@ AX = <a href="errors.html">error cod

DJ, who and how maintains the Web docs?

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 18 Feb 2024 11:35:11 +0100
I'm sending another simple documentation change. In documentation for
getting and setting attributes is written wrong name of the structure
field in which is stored number pages.
--- src/libc/dpmi/api/d0506.txh
+++ src/libc/dpmi/api/d0506.txh
@@ -20,7 +20,7 @@ not by Windows.
This function retrieves the attributes of a number of pages. Pass the
--- src/libc/dpmi/api/d0507.txh
+++ src/libc/dpmi/api/d0507.txh
@@ -20,7 +20,7 @@ not by Windows.
This function sets attributes of a number of pages. Pass handle in
@code{@var{info}->handle}, offset within block in
@code{@var{info}->address}, and number of pages in
words which specify the new attributes.
@xref{__dpmi_get_page_attributes}, for the definition of the page
attribute word.

Thanks, installed.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 25 Feb 2024 12:55:26 +0100
Hello, I have there another documentation change. It fixes mistake in
__dpmi_map_conventional_memory_in_memory_block() function. This function
takes linear address, not the physical one (as defined in DPMI 1.0 spec).

What exactly is the difference between a physical address below 1MB
and the linear address there?

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 25 Feb 2024 17:51:54 +0100

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

Date: Sun, 25 Feb 2024 12:55:26 +0100
Hello, I have there another documentation change. It fixes mistake in
__dpmi_map_conventional_memory_in_memory_block() function. This function
takes linear address, not the physical one (as defined in DPMI 1.0 spec).

What exactly is the difference between a physical address below 1MB
and the linear address there?

I'm not sure now if I understood it correctly. But my understanding of
the spec is that DPMI host which supports paging may page-out also
linear addresses below 1 MB.

Really? IME, no DPMI host does that. DOS memory is always mapped
1:1, AFAIR.

There are DPMI functions 0602H and 0603H which client may use to
enable/disable paging for memory below 1 MB. And once paging is
active then virtual linear address does not have to match physical
address.

Maybe the documentation should actually include all that, instead of
just using the confusing term "linear address" for what most DJGPP
hackers will think as "physical address".

[A. Wik ([e-mail]) [via [e-mail]]]

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
What exactly is the difference between a physical address below 1MB
and the linear address there?

I'm not sure now if I understood it correctly. But my understanding of
the spec is that DPMI host which supports paging may page-out also
linear addresses below 1 MB.

Really? IME, no DPMI host does that. DOS memory is always mapped
1:1, AFAIR.

Windows maps VMs one at a time into the low 1 MB, although the memory
that was in use when Windows started is replicated (at the same linear
address) in all the VMs. A VM is approximately a "DOS box", but there
is always a so-called "system" VM in which (usually) the GUI is
running.

There is also expanded memory (LIM EMS) that involves mapping the
"expanded" memory into or out of a program's low 1 MB address space.

-Albert.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 25 Feb 2024 19:28:07 +0000

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

I'm not sure now if I understood it correctly. But my understanding of
the spec is that DPMI host which supports paging may page-out also
linear addresses below 1 MB.

Really? IME, no DPMI host does that. DOS memory is always mapped
1:1, AFAIR.

Windows maps VMs one at a time into the low 1 MB, although the memory
that was in use when Windows started is replicated (at the same linear
address) in all the VMs. A VM is approximately a "DOS box", but there
is always a so-called "system" VM in which (usually) the GUI is
running.
There is also expanded memory (LIM EMS) that involves mapping the
"expanded" memory into or out of a program's low 1 MB address space.

I think there's a misunderstanding here. The issue at hand is whether
the DOS memory's linear address, as it appears within a certain VM,
can ever have the value above 1MB. If the linear address is _always_
below 1MB, then for all practical purposes it is the same as the
"physical address", since what the VM does under the hood is none of
the business of the DJGPP programmer.

[A. Wik ([e-mail]) [via [e-mail]]]

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

Date: Sun, 25 Feb 2024 19:28:07 +0000

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

I'm not sure now if I understood it correctly. But my understanding of
the spec is that DPMI host which supports paging may page-out also
linear addresses below 1 MB.

Really? IME, no DPMI host does that. DOS memory is always mapped
1:1, AFAIR.

Windows maps VMs one at a time into the low 1 MB, although the memory
that was in use when Windows started is replicated (at the same linear
address) in all the VMs. A VM is approximately a "DOS box", but there
is always a so-called "system" VM in which (usually) the GUI is
running.
There is also expanded memory (LIM EMS) that involves mapping the
"expanded" memory into or out of a program's low 1 MB address space.

I think there's a misunderstanding here. The issue at hand is whether
the DOS memory's linear address, as it appears within a certain VM,
can ever have the value above 1MB. If the linear address is _always_
below 1MB, then for all practical purposes it is the same as the
"physical address", since what the VM does under the hood is none of
the business of the DJGPP programmer.

Linear V86 addresses are obviously below 1 MB, but (via the page
tables) they can be (and in Wndows often are) mapped to any physical
address, including above 1 MB.

-Albert.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Mon, 26 Feb 2024 08:23:27 +0000

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
I think there's a misunderstanding here. The issue at hand is whether
the DOS memory's linear address, as it appears within a certain VM,
can ever have the value above 1MB. If the linear address is _always_
below 1MB, then for all practical purposes it is the same as the
"physical address", since what the VM does under the hood is none of
the business of the DJGPP programmer.

Linear V86 addresses are obviously below 1 MB, but (via the page
tables) they can be (and in Wndows often are) mapped to any physical
address, including above 1 MB.

Of course. But the misunderstanding I was pointing out is exactly
this: a programmer doesn't care about those page tables in this case,
because DOS memory is by definition "physical".

We basically agree about the facts, but not about their impact on the
documentation that is the subject of this thread.

[A. Wik ([e-mail]) [via [e-mail]]]

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]

Date: Mon, 26 Feb 2024 08:23:27 +0000

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
I think there's a misunderstanding here. The issue at hand is whether
the DOS memory's linear address, as it appears within a certain VM,
can ever have the value above 1MB. If the linear address is _always_
below 1MB, then for all practical purposes it is the same as the
"physical address", since what the VM does under the hood is none of
the business of the DJGPP programmer.

Linear V86 addresses are obviously below 1 MB, but (via the page
tables) they can be (and in Wndows often are) mapped to any physical
address, including above 1 MB.

Of course. But the misunderstanding I was pointing out is exactly
this: a programmer doesn't care about those page tables in this case,
because DOS memory is by definition "physical".
We basically agree about the facts, but not about their impact on the
documentation that is the subject of this thread.

Perhaps you mean that the distinction doesn't matter, because the
addresses are always mapped in while the VM is running? But the
distinction does matter if you're going to pass the address to a
hardware device. It can also matter if you're going to do certain
things with paging, such as turning it on or off or in some cases,
when you're manipulating the page tables.

-Albert.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 25 Feb 2024 13:42:23 +0100
Hello, the next documentation change is for __djgpp_map_physical_memory()
function. Document requirements / restrictions for out_addr/num_bytes
parameters and extend example how to use this function. I think that the
full example is useful because without it I had to read djgpp source
code to understand what kind of pointer I can pass for out_addr. If you
like this change, feel free to reformat or rephrase new description.
--- src/libc/dpmi/helper/mapmem.txh
+++ src/libc/dpmi/helper/mapmem.txh
@@ -21,6 +21,22 @@ be set to @code{EINVAL} and the routine will fail.
This routine properly handles memory ranges that span multiple DPMI

Please specify function by their name alone, as in @code{sbrk},
without the parentheses. "sbrk()" looks like a call to 'sbrk' with no
arguments, which is not what you mean here. Same with references to
other functions in the patch. (I realize that the fashion of
referencing functions by using the parentheses exists out there in
other projects, but we don't follow it here.)

Thanks.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Tue, 27 Feb 2024 23:51:19 +0100

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
without the parentheses. "sbrk()" looks like a call to 'sbrk' with no
arguments, which is not what you mean here. Same with references to
other functions in the patch. (I realize that the fashion of
referencing functions by using the parentheses exists out there in
other projects, but we don't follow it here.)
Thanks.

It is the only issue in this change? If yes, would you trivially change
it before applying?

Done, thanks.

[Eli Zaretskii ([e-mail]) [via [e-mail]]]

Date: Sun, 25 Feb 2024 12:55:26 +0100
Hello, I have there another documentation change. It fixes mistake in
__dpmi_map_conventional_memory_in_memory_block() function. This function
takes linear address, not the physical one (as defined in DPMI 1.0 spec).

Thanks, installed.

[DJ Delorie]

Post by Eli Zaretskii (***@gnu.org) [via ***@delorie.com]
DJ, who and how maintains the Web docs?

Me. Patch applied. Thanks!