apple2e: fix 80/40 and language switches, add additional UK and French Apple IIe/c variants

[as-tb-dev]

• added European Apple IIe/IIc variants:

  • added additional Apple IIe UK variants of Apple IIc and the Platinum Apple IIe
  • added French variants of Apple IIc and Unenhanced and Platinum Apple IIe
  • made minor corrections to the mapping of characters (PORT_CHAR) for the European Apple IIe/IIc keyboard layouts. This improves the keyboard when used in natural mode.

• 80/40 column switch fixes:

  • removed 40/80 column switch from Apple IIc+
  • added 40/80 column switch to Franklin Ace 500 and Laser 128 series

• keyboard/language switch implementation changes:

  • added QWERTY/DVORAK selection mod to US Apple IIe model. ref: Apple IIe Hardware: Dvorak Keyboard Layout (May 25, 1989) from the Apple Tech Info Library
  • added QWERTY/DVORAK switch to Laser 128 series
  • added local/US keyboard switch to French, UK, and Spanish Apple IIe and IIc variants, as well as tk3000, spectred, and prav8c machines. These switches change both keyboard layouts and text-mode character sets.
    • Apple IIe documentation for international models, including French, document the language switch. However, the French keyboard ROM ("341-0326-a.f12") currently used by MAME does not have the US keyboard mapping, but instead has 2 identical copies of the French AZERTY keyboard mappings. Due to the lack of US QWERTY in the "341-0326-a.f12", created a new file called "342-0326-a.f12" that uses the first 1024 bytes of "341-0326-a.f12" and the first 1024 bytes of the UK KBD ROM "341-0150-a.e12". Marked this new KBD ROM as 'bad'.
    • The newly added Unenhanced French IIe is configured using a good 342-0153-A KBD ROM dump and a 341-0163-a.e9 character ROM that was created by using 342-0274-a.e9 with the MouseText removed. Marked this created character ROM as 'bad', however, it may by chance be an exact match of a good dump
  • added character set selection switch, enabling/disabling MouseText, to Franklin ACE. This switch changes text-mode character sets without changing the keyboard layout.
  • moved language/keyboard selection to its own configuration I/O port: kbd_lang_select. This selection use each nibble of the port byte to hold keyboard ROM and character ROM offsets
    • this is mostly to add some flexibility since different machines have different combinations of offsets between keyboard and video ROMs when the switch is present, allowing code to be shared

• fixed bug where Apple IIc+ may crash when booting 5 1/4" disks due to uninitialized disk related variables

• embedded more notes about keyboard, keypad, and regional variants in the apple2e.cpp file

[colinleroy]

Hi,

As a french Apple II user, I'm interested in that!

Issue: Apple //e documentation for international models, including French, document the language switch. However, the French keyboard ROM ("341-0326-a.f12") used by MAME does not have the US keyboard mapping, but instead has 2 identical copies of the French AZERTY keyboard mappings. Many sites document the French keyboard ROM as 342-0306-A and not "341-0326-A".

Could I somehow help by dumping my french IIc char ROM? I fear this requires specific hardware?
As a fallback, would it be possible to mix 341-0326-a.f12 and 341-0132-d.e12 manually and use a "fake ROM" or is it too awful? I built one this way:

#include <stdio.h>
#include <string.h>

int main(void) {
  FILE *us  = fopen("/home/colin/Downloads/341-0132-d.e12", "rb");
  FILE *fr  = fopen("/home/colin/Downloads/341-0326-a.f12", "rb");
  FILE *mix = fopen("fake_us_fr.rom", "wb");
  unsigned char buf[0x400];

  fread(buf, 1, 0x400, us);
  fwrite(buf, 1, 0x400, mix);

  fread(buf, 1, 0x400, fr);
  fwrite(buf, 1, 0x400, mix);

  fclose(fr);
  fclose(us);
  fclose(mix);
}

fake_us_fr.zip

[as-tb-dev]

Hi,

Correct. Special hardware is required to dump either the keyboard or character ROMs since neither are CPU addressable on a real Apple IIe/IIc machines.

Merging MAME's US and French keyboard ROMs (QWERTY-half of the US and either half of MAME's existing French ROM) would make the US keyboard layout functional for the French Apple IIe/IIc variants. I suspect the order is AZERTY first and then QWERTY.

Regarding whether creating the ROM that MAME uses by merging the two is good, my opinion (but I am just a contributor) is that while it is not as good a real dump, it can be marked with a BAD_DUMP tag in MAME so that it is clear that it is not a real dump.

Since using it would be an improvement in emulation accuracy without adding regression, it can be considered for submission for in a PR. For the filename, I assume that it is best to name it after the ROM that it trying to emulate as best as possible. After submitting the draft PR above, I found another yet another site that IDs the French keyboard ROM as "342-0326-A".

I added a commit for this that changes the keyboard ROM for the existing apple2eefr with the suggestion you made (except reversing the order) and can confirm that the French/US keyboard switch now works correctly.

[Altomare]

Dumped two French Apple IIe keyboard ROMs, hope that helps.
Both have the same ROM version and the dumps match.

Model: A2S2064F
Keyboard: AZERTY, the QWERTY layout being visible as grayed markings too.
Motherboard markings:

• 820-0073-B
• F607-0264-F

ROM: 342-0153-A, Copyright Apple 1983
Apple IIe Keyboard ROM - 342-0153-A - FR.zip

[as-tb-dev]

A site I found that lists parts numbers refers to "341-0153" as the "Keyboard ROM French/USA" and the "342-0326-A" as "(Enhanced) Keyboard ROM French/USA".

With "341-0153", the lock key below Shift is a 'Caps Lock' key and pressing Shift with Caps Lock down do not cancel each other out.
With "341-0326-A", the lock key below Shift is a 'Shift Lock' key and pressing Shift with Shift Lock down does cancel each other out.
The "341-0153" behavior is also how Apple IIe/IIc machines work with other keyboard layouts. The "341-0326-A" behavior is unique to the French keyboard layout, but apparently was not the original design.

Page 36 of Apple //e Guide de l'utilisateur (F030-0356-B) documents the behavior of a French Apple IIe being as per "341-0153".
The Second edition of the Apple IIc Technical Reference and the 1987 edition of the Apple IIe Technical Reference Manual document the behavior being as per "342-0326-A". They make no mention of the older behavior.

I created a new 'apple2efr' device in the last commit that uses "341-0153". The unenhanced 341-0163-a.e9 can be created from the enhanced 342-0274-a.e9 by replacing the MouseText characters with a second set of the uppercase letters:
dd if=342-0274-a.e9 of=341-0163-a.e9
dd if=342-0274-a.e9 of=341-0163-a.e9 bs=256 skip=0 seek=2 count=1 conv=notrunc
dd if=342-0274-a.e9 of=341-0163-a.e9 bs=256 skip=16 seek=18 count=1 conv=notrunc

I tagged 342-0163-a.e9 as a BAD_DUMP.

[as-tb-dev]

@colinleroy, after further inspection, it looks like the UK keyboard layout, 341-0150-A, is a better candidate than the US keyboard layout, 341-0132-D, to use as the basis of the missing US layout of Enhanced French keyboard layout 342-0326-A. UK and France share the same physical keyboard (ignoring the symbols on the keys), but the US one is different. This has a ripple effect that causes `~ and | keys to be swapped. My latest commit uses the first half of 341-0326-a.f12 and the first half of 341-0150-a.e12 to create the new 342-0326-a.f12.

[colinleroy]

@colinleroy, after further inspection, it looks like the UK keyboard layout, 341-0150-A, is a better candidate than the US keyboard layout, 341-0132-D, to use as the basis of the missing US layout of Enhanced French keyboard layout 342-0326-A. UK and France share the same physical keyboard (ignoring the symbols on the keys), but the US one is different. This has a ripple effect that causes `~ and | keys to be swapped. My latest commit uses the first half of 341-0326-a.f12 and the first half of 341-0150-a.e12 to create the new 342-0326-a.f12.

Seems like a better idea indeed :)

[rb6502]

I've been watching these changes and I appreciate them very much! Big thanks also @Altomare for the keyboard dump! European Apples are not well documented outside of the small bits of info about PAL timings in Sather's "Understanding the Apple IIe" so I don't even know what unique keyboard and video ROMs exist. I'll give a proper review when it's out of draft.

[cuavas]

You’re supposed to use KEYCODE_BACKSLASH2 for this key.

[as-tb-dev]

My last commit adds KEYCODE_BACKSLASH2, but without removing KEYCODE_BACKSLASH for all ISO layouts (UK, FR, and ES). The reason I did not remove KEYCODE_BACKSLASH is that KEYCODE_BACKSLASH2 does not exist as a key on ANSI keyboards, and in the case of Apple IIe/IIc machines, the ISO keyboard has the same number of keys as the North American keyboard - unlike PCs where the ISO keyboard has one extra key. On the Apple IIe/IIc, it is just two keys get swapped in physical position and in how they get encoded in the ROM. Please advise if having both backslashes mapped is correct.

Regarding taking this PR out of draft mode, the main thing I have not done yet is create a new keyboard layout for the UK variant of the Platinum Apple IIe. For that, I wanted to discuss a long-term design for the International Apple computers.

• My original thought was that they could all share the same PORT_CODE/PORT_CHAR defined layout as the US variant. However, `~ and | encodings are swapped between North American and ISO layouts make that design impossible.
• A similar design to the above would be to have 2 US layouts (ISO US layout for UK, France, Italy, Germany, Sweden, Spain and North American US layout for US, Canada, and Latin American machines)
• Would MAME users expect to see the ''Input Assignments (this system)" to show the localized keyboard, or is having the US layout shown an option - given that the real Apple IIe/IIc machines have selection switches to pick either of the two layouts? This would impact which of the two Apple IIe/c keyboard layouts will work when the keyboard mode is set to 'natural'. Currently, the localized one works in 'natural' mode, but the US one will work instead if the above change is made.

[cuavas]

No, KEYCODE_BACKSLASH is present on ISO keyboards.

Using this image for reference:

• KEYCODE_BACKSLASH is for the key immediately to the left of return on the home row, with the £ pound sign on it.
• KEYCODE_BACKSLASH2 is for the key immediately to the right of the left shift key on the bottom row, with angle brackets on it.

The key corresponding to KEYCODE_BACKSLASH2 on ISO keyboards simply doesn’t exist on ANSI or JIS keyboards. Users need to reassign it manually. Assigning KEYCODE_BACKSLASH2 and KEYCODE_BACKSLASH to that key by default will not do what people expect.

[cuavas]

My original thought was that they could all share the same PORT_CODE/PORT_CHAR defined layout as the US variant. However, `~ and | encodings are swapped between North American and ISO layouts make that design impossible.

And that’s a bad idea, and not how we do things in MAME. But remember PORT_MODIFY is a thing so you can reduce duplication if the matrix is mostly the same.

Would MAME users expect to see the ''Input Assignments (this system)" to show the localized keyboard, or is having the US layout shown an option - given that the real Apple IIe/IIc machines have selection switches to pick either of the two layouts? This would impact which of the two Apple IIe/c keyboard layouts will work when the keyboard mode is set to 'natural'. Currently, the localized one works in 'natural' mode, but the US one will work instead if the above change is made.

No, always showing the US layout is not what users would expect. For systems with plug-in keyboards, we provide options for language variants known to exist, even if they only differ in key cap labels, e.g. see these files:

• Mac Plus keyboards (US, France, Japan – only key caps differ)
• Original Mac keyboards (US, UK, France, Italy, Japan – ANSI and ISO use different scan codes as well as different physical layout)
• Sun Type 3/4/5 keyboards (Type 5 had ANSI, ISO and JIS physical layouts – US, UK, Sweden and Japan variants confirmed)
• Amiga keyboards (numerous language variants)

[as-tb-dev]

Thanks. I have modified the genuine Apple //e keyboard definitions to all base upon a single layout and then use PORT_MODIFY to make the minimally required alterations. With this, future expansion for additional localized layouts will not complicate things too much.

Note though that unlike the Amiga where a US keyboard can be unplugged and French keyboard plugged in, with the Apple //e, there is just a physical switch to toggle between US and localize keyboards 'live'. Whether we pick the US or localized layout, for the PORT_CHAR, the other one will technically be missing. Would the emulated Apple //e keyboard have to become a 'slot' device to correctly implement both language layouts at 'Input Assignments' menu? If it is better just to just support 1 at the UI (and natural keyboard level), then the localized one is better.

I will look at the KEYCODE_BACKSLASH2 again for my next commit.

[cuavas]

It’s possible to use PORT_CONDITION to flip the key inputs when you change the state of the switch. Practicality depends on the number of keys that need to have their labels switched when the layout switches.

The Swiss Amiga keyboard needs to do this because a few keys switch function between French and German modes (shift states reversed): https://github.com/mamedev/mame/blob/mame0269/src/devices/bus/amiga/keyboard/matrix.cpp#L663

[as-tb-dev]

Thanks. PORT_CONDITION works if I put the condition after each PORT_BIT and create a revert PORT_BIT with the opposite condition (e.g. ISO US keyboard entries for each localized keyboard). I agree that it is only practical if there are not too many keys, but I think there may be quite a bit in the long term if more layouts are added. I tried applying PORT_CONDITION to a 'PORT_MODIFY' line (in case it could be used to disable the entire port-modification when the condition was false, but that did not work). For this PR, I am keeping the existing design where only the localized keyboard works in natural keyboard mode.

Regarding the Apple's ISO keyboard layouts, I tried the changes with a physical ISO PC keyboard just now, and I agree, the KEYCODE_BACKSLASH2 is needed for the <>| key and the KEYCODE_BACKSLASH is needed for the `~£ key as you suggested. My most recent commit makes that change. The current version of MAME (i.e. 270) has KEYCODE_TILDE for the <>| key. I have not removed KEYCODE_TILDE as a mapping to that key since KEYCODE_TILDE would otherwise not be mapped to anything and I therefore expect that it be the key that those without a physical KEYCODE_BACKSLASH2 key would manually map the <>| to. If the correct keys are working for someone using a physical ISO keyboard, is it OK if an extra works by default too? If not, I will remove the KEYCODE_TILDE mapping.

[as-tb-dev]

@rb6502, my latest commit adds lists of variants I have read about in various Apple documents as well as a list of references. ROM numbers are not well documented for international models. There are many unofficial lists I found on the Internet, but none appear to be complete.

[rb6502]

@cuavas Are you OK with the layout and port usage here now?

[cuavas]

Why are the PORT_CHAR swapped here? Don’t unshifted keys produce uppercase by default? Or am I remembering wrong?

[as-tb-dev]

On Apple IIe/IIc machines, unshifted keys produce lowercase letters by default. However, many Apple IIe/IIc users would keep the caps lock button pressed to run older Apple II/II+ era applications or to type DOS 3.3 commands.

[cuavas]

@cuavas Are you OK with the layout and port usage here now?

I’m OK with the default assignments.

It might be useful to add a PORT_CODE(KEYCODE_RSHIFT) to the shift key to make it a bit more natural for people using keyboards with distinct shift keys.

The one thing that’s concerning me a little is that this swaps the order of the lowercase and uppercase PORT_CHAR, which means for the purpose of -autoboot, the “UI Paste” function, and whatever the Lua function for typing characters is called, the state of the Shift key will be reversed: currently, pasting lowercase is shifted and pasting uppercase is shifted; this PR will reverse that so pasting lowercase is unshifted and pasting uppercase is shifted. Is that potentially going to break things people are doing?

[as-tb-dev]

@cuavas Are you OK with the layout and port usage here now?

I’m OK with the default assignments.

It might be useful to add a PORT_CODE(KEYCODE_RSHIFT) to the shift key to make it a bit more natural for people using keyboards with distinct shift keys.

I could not find any cases in apple2e.cpp where there was an LSHIFT without an RSHIFT. This seems to work OK for me with MAME 0.271.

I did just notice that 3 cases of RSHIFT are missing the PORT_CHAR(UCHAR_SHIFT_1). I added these just now.

The one thing that’s concerning me a little is that this swaps the order of the lowercase and uppercase PORT_CHAR, which means for the purpose of -autoboot, the “UI Paste” function, and whatever the Lua function for typing characters is called, the state of the Shift key will be reversed: currently, pasting lowercase is shifted and pasting uppercase is shifted; this PR will reverse that so pasting lowercase is unshifted and pasting uppercase is shifted. Is that potentially going to break things people are doing?

I have never used this feature myself. For sure the letter case in strings will be reversed and will be broken. For commands, it depends on the platform. ProDOS supports lowercase commands, but DOS 3.3 commands must be in uppercase. Filenames are case insensitive. Older applications and games will likely only work with uppercase.