February 2019 release to-do
(1) By tangent on 2019-01-29 21:29:32 [link]
As I see it, here are the only things left to do before I can tag the release and produce the binary media:
Document the external interface to the CC8 standard library, such as it is. I can do this, or you can, Bill.
Clarify "TD8E" vs "TD12K" in the docs. My vague sense is that these are related terms, but it's not clear to me what the distinction is. Since the SIMH docs talk only about TD8E, and that's the name of the hardware in question, I'd prefer to get rid of TD12K entirely, but if there's some necessary point to be made here, it should be done explicitly somewhere. Since this affects the calling interface to the
configurescript, the effects may be more than just to the documentation.
The ChangeLog should either list the differences between OS/8 V3F and V3D, or link to a document that does.
media/os8/patches/TECO-31.20.10M-5.05.patch8not have a
vin its name to match the form of the other TECO patch files? That is, rename it to
A bunch of stuff has changed recently, collectively causing total invalidation of the
test-os8-run corpus. Some of it could possibly be worked around, but there's enough of it that I'm ready to declare "test corpus bankruptcy" unless you can talk me down off the ledge, to mix a metaphor. :)
The recent CC8 changes have invalidated all of the
test-os8-run outputs that include CC8. That's half the tests right there.
Then there's a cosmetic change due to a new feature in the just-merged SIMH upstream changes, which allows you to force a SIGINT to the simulator to bring up an attached debugger. The simulator tells you about this feature, changing the text output. While we can deal with that in the
test-os8-run output sanitizer, it just brings me to...
The path sanitization code used on the prior test run is way overcomplicated. It uses four hairy regexes and results in an inconsistent number of directory elements in the output path. I've just checked in a much simpler replacement which accomplishes the same end goal of obscuring pointless local file structure differences, but it invalidates all exemplars involving an "attach" command, which is all of them.
I wouldn't have done the latter if the above changes weren't already going to force me to regenerate at least half the tests. I'm calling this an opportunity rather than a problem.
This does mean tagging the release will either have to wait ~10 days for test corpus regeneration, or we won't have a full test corpus by the time I tag the release this weekend. I'm leaning toward the latter, since simply re-testing a large subset of the corpus should be fine, by this point.
I'm in the middle of updating the ChangeLog, and I see that there is one last checkin on the smc85-cc8 branch that has not yet been merged down to trunk. Will it be merged before release, or is this the start of what should wait for the next release?
If you're going to merge it, will it affect the
os8-run test corpus rebuild?
I've been traveling and doing family stuff the past two weekends, and I see you've dove in and done a bunch of good new work.
There are actually two smc85 merges in my backlog. I intended to do them two weeks ago, but I'd not gotten to it.
My expectation is that it WILL affect the os8-run test corpus rebuild. Ian has fixed some of the C compiler bugs you flagged.
More soon, but I wanted to reply as soon as I saw questions from you.
Good to know.
I'll keep regenerating my test corpus since I'm doing a shuffled re-generation, so that statistically, I'll still be able to keep half of what I generate. Meanwhile, I can use the exemplars including CC8 in cross-platform tests.
You'll be happy to know that my changes to the log sanitizer in
test-os8-run appear to have not broken the tests. On my Pi 3, I've rebuilt most of the first 310 tests built on my Mac, with no change detected.
It sounds like this weekend will be too soon to release.
I just merged Ian's updated cc8 code into my branch.
It closes bugs reported on the cross compiler, and adds some functionality. These updates don't change the native C compiler. (However I see that there was a pending merge with trunk of OTHER cc8 changes. So although this most recent change set does not affect cc8.tu56, the previous un merged change set might very well affect it.)
I'm going to look over what's in my smc85-cc8 branch very soon, and merge it with trunk as soon as I confirm for myself that it is safe to do so.
As I said in my checkin and in private email: I did a run of 50 random tests with the latest trunk plus the latest smc85-cc8 branch.
The tests, when re-run on my Pi passed. So I feel confident that this merge is safe to put onto the trunk.
This removes the blocker for more extensive testing.
I have some documentation updates on the state of cc8. I'm a bit unclear on what you mean by "the extrernal interface to the CC8 standard library," though. Can you say more?
Yes this clarification is important. In which doc file would you like that information put?
Wow, I missed one file name with my convention? Sure. Go ahead and rename it if you get a chance.
I'm speaking of what's declared in
src/cc8/include/libc.h. Some of that is entirely nonstandard, like
itoa(), so we cannot rely on external documentation; we need our own. Some of it may conform entirely to the ISO C standard, though I doubt it. To the extent that any of it has the same name as an ISO C function but does not entirely conform, we should document the exceptions.
In composing this reply, I started to write up some easy discrepancies I found, but later moved it into what will become the CC8 manual, which started out as
src/cc8/README.md. You should give that a read, with particular attention to the "TBD: True?" markers, the nascent library section, and the surely-incomplete section on inline assembly.
It also occurs to me that the method by which the two compilers share LIBC should be documented, since it's implemented with inline assembly, a feature not present in the native compiler. I assume it's just cross-assembled, but where is that documented? For that matter, we should probably also explain how
cc8.tu56is produced, implicitly explaining the cross-compilation process that yields the native compiler binaries.
I can finish the first pass on this at least, though with your stronger SABR-fu and more up-to-date battle experience, I'll want your eyes to give it a sanity check afterwards.
Since I don't know the distinction myself — else I'd have just fixed it — my uninformed [non]sense is that the ChangeLog should talk only about TD8E to match the SIMH docs, the configure script should expect "td8e", not "td12k" to be consistent with "tc08", and if anything needs to be said about TD12K, it should probably go in
doc/os8-run.md, that being the place where "td8e" changes to "td12k" for a reason best known to you. (Or should "td8e" change to "td12k" in auto.def instead?)
On this note, the top-level README.md file doesn't mention
--boot-tape-configat all. What else is new and yet-undocumented?
This sounds like a task for you. It probably shouldn't go in the ChangeLog, as that's meant to be brief. I hesitate to put it in
doc, since that's for material that changes as the source tree changes. This feels like evergreen content, so it should go in the wiki; neither OS version is changing any more, yes?
I've checked in what I consider a "first pass" at documenting the CC8 LIBC, but I haven't yet run into much I can't figure out on my own yet. I'm getting close in some areas — the
fgetc() implementation is fairly hairy, for example — but I want to make at least one more pass before I consider it ready to be critiqued or taken over by someone more knowledgeable.
I've moved forward on some of the action items:
Re: #1 I've swept through the bug list and documented what was and was not done to cc8 and why. Most of the bugs are resolved with "Works as Designed." I've looked at cc8-manual.md, and will be suggesting some updates. Although your comment says you've completed a first pass, I wasn't sure if you were going to make more passes before wanting a review/revise pass from me.
One quick easy change you can make:
struct and union
are now supported in cc8, so you can delete the mention of them as missing functionality.
Let me know when cc8-manual.md is ready for my review.
Re: #2, #3: I just checked in a lot of drafty prose in ChangeLog.md explaining the differences v3d/v3f and TC08/TD8E.
I'd be grateful if you'd read them over and then let me know if there's a better place to store that information. (Since its nearly bed time, I was lazy and didn't include a link to os8-v3d-device-extensions.md, but THAT is the document that details the differences between V3D and V3F.)
While I was writing this reply, I see you've written in HACKERS.md clarification of the ticketing workflow.
Thanks for the clarification. Sorry for not following the workflow. Now I know what it is.
Mind you, it may be that my choice of "Works as Designed" was not necessarily intended as, "And is expected to stay that way for all time." However, I think Ian has taken the C compiler as far as he plans to for the foreseeable future, and I want to work on the Combined Kit, before I go back to it myself.
I've made another pass on the Ticket Processes section. It should clarify a few more things about how I think this thing should run.
The main point is, resolution is an end state, not an expression of intent. "Works as Designed" is a Judgement, not a mere observation or personal opinion. As a developer, you are empowered to make such judgements. Just be sure. :)
I wasn't sure if you were going to make more passes before wanting a review/revise pass from me.
I still intend to get back to it to do more work on it, mainly in filling out the standard library function descriptions, but I'll be busy tomorrow morning through the early afternoon at least, so if you want to take a pass at it yourself, that's a safe time to do it.
I just checked in a lot of drafty prose in ChangeLog.md explaining the differences v3d/v3f and TC08/TD8E.
Okay. I can't do anything useful with it now. (Fried and at the end of the Broadcast Day.) I'll probably end up moving it to the wiki tomorrow sometime.
I've moved this material from the ChangeLog into the wiki, along with doing some polishing:
I still want to know what the difference between TD8E and TD12K is. I assume "12K" is a reference to the need for a 12kW PDP-8 to run the TD8E driver, but why don't we just say "td8e" in the configure flag and os8-run scripts? Is there an important point to be made here, referring to an interface card in one case and a...not interface?...in the other?
The TD8E hardware, requiring so much CPU intervention meant that the system device driver was twice the size DEC expected any reasonable device driver to be. It was the first "two page system handler".
But OS/8 could only accommodate single page system handlers. The second page was a gross hack: It took 7600-7777 in field 2 OR you could buy a read only memory card that contained the necessary second page stuff. Since the JMS instruction writes to the first location of the called subroutine, writing PDP-8 ROM code is a challenge.
BUILD a TD8E system, you have your choice of two system drivers:
TD12Kwhere you have to have at least 12K of memory, and you sacrifice the top page of field 2.
TDROMwhere you have to have the TD8E ROM hardware.
The 12K option is more common because people were more willing to shell out for the ability to run bigger programs off their cheap tape drive, rather than sticking with 8K of memory, and a single purpose add-on board.
Oh and there are the following other bits of trivia:
That gross over-sized driver, and the hardware was such that each "Simple" DECtape controller could only control two drives.
TC08's more elaborate controller could handle 8 drives.
BUILD you see additional device drivers:
TD8Awhich is a non-system handler for controlling drives 0 and 1.
TD8Bwhich is a non-system handler for controlling drives 2 and 3.
TD8Cwhich is a non-system handler for controlling drives 4 and 5.
TD8Dwhich is a non-system handler for controlling drives 6 and 7.
To have all 8 drives, you needed 4 controller cards.
"Non-system" driver means you can't boot from the device, you can just read and write data on it. A typical high-end system would have an RK05 system device, and a pair of DECtape drives with a single TD8E controller. You'd use the
RK8E system device driver, and the
TD8A non-system DECtape driver.
A bootable DECtape would activate the
TDROM system device driver and an
RK05 non-system device driver for the disk.
Ah: so we can't just talk about TD8E, because that's ambiguous. Got it. I'll update the wiki and top-level README at some point, then.
(21) By tangent on 2019-02-13 03:19:41 in reply to 20
The wiki part's done.
I'm putting off the README.md part because it requires documenting
--boot-* as well. I might get to that before going to sleep tonight.