digidotcom/dcrabbit_9

This repository is the Open Source release of the libraries and sample code from Dynamic C 9, an integrated development environment for Digi International's embedded systems based on the Rabbit 2000 and 3000 microprocessors.

Dynamic C 9

for Rabbit-based embedded systems

Description

This repository is the Open Source release of the libraries and sample code from Dynamic C 9, an integrated development environment for Digi International's embedded systems based on the Rabbit 2000 and 3000 microprocessors.

It is of limited use without the rest of the IDE and the appropriate target hardware. See the Installation section for instructions on installing Dynamic C 9.62 and updating its libraries and samples with the code in this repository.

The release branch is a RELEASE software release which is fully QA-tested and supported by Digi International. The master branch is an ALPHA software release which has received limited functional/unit testing.

Licensing

The MPL 2.0 license covers the majority of this project with the following exceptions:

• The ISC license covers the contents of the Applications, RabbitLink and Samples directories.

Installation

Instructions on using Git and GitHub are beyond the scope of this document. If you are new to using Git, we recommend the Windows GUI Git Extensions. Their website includes a manual and video tutorial. The program has a command-line "Git bash" tool, available in the Tools menu, that you can use to execute the script below.

To make use of this code, either start with an existing (backed-up) Dynamic C 9.62 installation, or download and install Dynamic C 9.62, followed by the Embedded Security Pack and finally, the Dynamic C 9.62 Library Patches. Portions of the Embedded Security Pack and Library Patches aren't tracked by this repository, so it is necessary to run those installers.

Next, add the GitHub repository to the directory. These instructions have you creating a private branch where you can store your own changes to the libraries and samples, merging them in with Digi International's changes. It assumes you've already changed to the directory with Dynamic C installed (e.g., cd /c/DCRABBIT_9.62).

# Connect the Dynamic C installation with the GitHub repository,
# and download all of the branches and tags.
git init
git remote add origin https://github.com/digidotcom/DCRabbit_9.git
git fetch --tags

# Configuration options to ignore file modes and preserve line endings
# (since this is a Windows-only repository).
git config core.filemode false
git config core.autocrlf false

# Reset to the patched 9.62 release (without changing directory contents).
git reset 9.62-patch2

# Get the .gitignore file from the repository.
git checkout .gitignore

# Create a private branch using the 9.62 release as a start point.
git checkout -B mybranch

At this point, git status will show any changes to the directory you have made since the original installation. You should reset any accidental changes, or create commits to track intentional changes.

Once you have processed all of your changes, you can cherry-pick individual commits from the master and release branches, or merge either branch, in its entirety, into yours.

dcrabbit_9's Issues

Compiler bug in DC 9.30 and later generates incorrect opcode sequence

Digi has discovered a bug present in Dynamic C 9.30 (but not 9.25) related to code generation for assigning 8-bit values to 16-bit variables via a pointer. The bug has been in all releases of Dynamic C from 9.30 through 9.62A.

Some examples of affected C statements:

pt->int_val = char_val;          // impacts pointers to structures
*stack_int_ptr = char_val;       // impacts pointers on stack
int_array[7] = char_val;         // impacts arrays w/constant index
int_array[int_val] = char_val;   // impacts arrays w/variable index
int_ptr[7] = char_val;           // impacts array syntax with pointer
*(int_ptr + 7) = char_val;       // impacts dereferenced pointer
int_ptr[int_val] = char_val;     // impacts pointer w/variable index

The work around is quite simple. Users can either wrap char_val in parentheses, or explicitly cast it to int:

*int_ptr = char_val;            // affected
*int_ptr = (char_val);          // workaround
*int_ptr = (int)char_val;       // workaround

Dynamic C 9.25 generates the following 11-byte opcode sequence – upon entry, HL holds the address of the integer destination:

1de9 E5       push   hl                10
1dea 2A1BB8   ld     hl,(0xB81B)       11
1ded 2600     ld     h,0x00             4
1def FDE1     pop    iy                 9
1df1 FDF400   ld     (iy+0),hl         13

Note the protection of HL before loading the byte at 0xB81B, and the use of IY to write the 16-bit value to memory.

Starting with Dynamic C 9.30, the compiler generates this 9-byte sequence:

1a88 3A18BA   ld a, (0xBA18)                 9
1a8b 6F       ld l, a                        2
1a8c 2600     ld h, 0x00                     4
1a8e DDF400   ld (hl + 0), hl                13

Effectively overwriting the destination address with the value to write.

To assess impact, customers can search their binary files for the sequence 6F 26 00 DD F4 00, which should be unique and unlikely to appear outside of this specific opcode sequence. They can also search the assembly listing (.LST file) for the DDF400 sequence corresponding to ld (hl + 0), hl which is unlikely to occur outside of this bug.

Users can patch the sequence after the ld a, (0xBA18) with the following opcodes, making it possible to "fix" existing .bin files containing the 6F 26 00 DD F4 00 sequence in cases where it isn't possible to update and re-compile source code.

77       ld (hl), a
23       inc hl
AF       xor a
77       ld (hl), a
2B       dec hl         ; restore original HL value
00       nop            ; keep original byte count

We don’t necessarily have to restore the HL value after the write, but we have two bytes to spare and might as well do it instead of just adding another NOP.

We are adding this as a KNOWN ISSUE and have no plans to update the compiler to fix this bug. This is the first report of the problem since releasing Dynamic C 9.30 over 16 years ago.

Instability to start the application download

When building to target I am having often a failure to start the download when using DC9.62A.
It fails three out of four attempts then it works, and it keeps working until I have to powercycle the target.
The RFU utility is not having this behaviour it is always doing the download so I think there is a timing issue in DC9.62A download procedure.
The target is a custom rabbit 2000 board and I have no availability of regular rabbit 2000 sbc or modules to do a cross check of this behaviour.
The DC9.62A host pc is a win11pro i7-11850H with 32GB ram so it may be "too fast" in some of the early download steps.
The serial line is a FTDI with the default windows driver and adapter cable is an original rabbit one.
Let me know if I can provide more useful data to investigate the matter.

extract_flash.c will fail for large programs on dual-256K flash boards

IIRC, the memory layout of dual flash boards places the UserBlock and System ID Block at the top of the first flash. I think this was to allow for storing data on the second flash, or possibly an alternate firmware image (downloader on first flash, application on second flash).

The current version of Samples/extract_flash.c doesn't take that mapping into account, and won't be able to dump a large firmware image that skips over the UserBlock and System ID Block.

Potential /OE timing issues on 29MHz products with 55ns flash

Due to the obsolescence of the previously qualified 45ns flash memory for select SKUs in the Rabbit family’s product line, Digi qualified 55ns flash from the same supplier and started manufacturing boards with that flash in 2020 Q4.

Calculations from the Rabbit 3000 data sheet and scope captures of flash memory reads show the processor timing meeting the flash memory's timing requirements with a narrow margin. In typical operation, the BIOS startup code enables an "early output enable (/OE)" feature that provides a wider timing margin.

There are two instances when that is not the case, and products are operating with the narrow margin:

• If the spectrum spreader is disabled (macro ENABLE_SPREADER set to 0).
• A brief moment (less than 10 opcodes) between enabling the clock doubler and enabling the spectrum spreader.

rabbitbios_use_to_compile_pilot.c lacks license info

The file just states "Copyright (c) 1999-2002 Z-World." I guess one can deduce that it should be MPL or something compatible, since it is meant to be linked with MPL pilot.c, but it would still be better to have that explicitly in the file.

Source for coldload.bin, pilot.bin?

The repository contains coldload.bin and pilot.bin, but no source for them.

Is the source the same as the one used in Dynamic C 10, i.e. as in https://github.com/digidotcom/DCRabbit_10/blob/master/ColdBoot/COLDLOAD.C and https://github.com/digidotcom/DCRabbit_10/blob/master/ColdBoot/PILOT.C?

Build to target on custom board without ID block

I am dealing with a custom board that has no ID block data.
The targetless build is working well with the data I set in the project options and by downloading the binary with RFU utility i can confirm that the application is working.
If I do a build to target the build fails because the data retrieved from the custom board makes the compiler believes there is not enough memory.
I tried to define in the project options the memory size in 4k blocks as follow but that data is ignored
BOARD_TYPE=0xFFFF
FLASH_SIZE=64
RAM_SIZE=32
Is there a way to enforce ram and flash size when doing a build to target so that the compiler is happy and the debugger becomes available?

Bootstrapping sequence documentation improvement

I've read the documentation (4e527a9) and found it helpful.

A few small suggestions:

• Add references to existing documentation (TN206 and chapter 4 of the Rabbit 2000 designers handbook)
• Use terminology more consistent with existing documentation: "initial loader" instead of "cold loader", "secondary loader" instead of "PILOT bios".
• Regarding "Set RTS, clear DTR (already cleared previously).": Wasn't RTS also already set previously? Since we have a comment on DTR, there should also be one on RTS.

Philipp