[J-core] Turtle Board Documentation

Rob Landley rob at landley.net
Wed Mar 24 09:32:48 UTC 2021

On 3/8/21 4:08 PM, Patrick Oppenlander wrote:
> Hi,
> I've received my Turtle Board. Thanks for sending that to the opposite
> side of the planet!
> Is there a documentation repository somewhere?

Oops. Gmail's spam filter went feral again and I forgot to check it, sorry. (I
emailed you off list to make sure the board arrived intact and you pointed me at
this thread, which I've fished out of spam now. Sorry about that.)

> I'm looking for information on how the boot process works, and will
> probably need schematics (at least for the FPGA I/O) for this to be
> useful.

Schematics: https://github.com/j-core/jcore-jx

The device tree source gives you SOC I/O info the Linux drivers use to talk to
the hardware implemented in the bitstream:


The manual's a bit big for the mailing list, sent separately.

Here's what I told Kurt and Joshua when I sent them a board:

> I couldn't scrounge up a spare SD card to ship in the board (and the two places
> within walking distance I knew to buy them have both gone out of business since
> the pandemic started), so remember the connector is on the bottom of the board
> so you put the card in upside down, I.E. the pins facing up towards the board.
> Also it's press-to-click, press again to release (somebody tried to pull the
> card out with pliers once, they broke the socket, don't do that). Yeah we should
> do quickstart youtube video...
> The usb mini-b connector that powers the board also provides serial console, in
> Linux it's /dev/ttyACM0. On the target side it's running at 115200 and on the
> host side it's the USB serial cdc-acm packet protocol so I don't think the speed
> matters, but I generally "sudo busybox microcom -s 115200 /dev/ttyACM0" out of
> habit. (P.S. there's old instructions on j-core.org about uninstalling
> "modemmanager" if you suffer from that. Devuan didn't have that by default, and
> I dunno what any distros that use systemd have been doing since they started
> inflicting systemd on poor unsuspecting users. I'm slowly updating j-core.org
> but most of it's still a bit stale...)
> Attached is a manual that says how to flash stuff. There are 3 levels of
> software in the board:
> 1) 8-bit atmel boot processor has a firmware you can reflash (and should never
> need to). That loads the xilinx on power-up, brings up a reflash-the-xlinux boot
> menu when you press the white button (and switches back to run mode when you
> press it again), and forwards USB serial packets at runtime (cheaper than a
> separate usb serial chip).

FYI, the atmel bootloader source is https://github.com/j-core/TurtleAtmel but
you need an 8-bit toolchain to build it. (I haven't got it but it's the same one
Arduino uses I think?)

> 2) the xilinx bitstream lives in SPI flash. The program in the atmel handles
> reflashing it (press the tiny white rectangular button for the reflash menu), it
> reads the file "fpga.bin" from the sdcard when doing so.
> 3) The boot ROM in the j2 bitstream loads "vmlinux" from the sd card, does basic
> ELF relocation, and jumps to the _start address.

Boot rom source: https://github.com/j-core/bootrom

Which sadly needs a bare metal ELF toolchain to build, which is so bit-rotted
its build is EXPECTED to break and nobody's bothered to fix it. Instructions
here: https://lists.j-core.org/pipermail/j-core/2019-October/000867.html

The "hello world" kernel can be built with the fdpic toolchain, and Linux builds
with the fdpic toolchain, so you CAN build bare metal code with that (it's
mostly differing symbol prefixes, which impacts libgcc.a. The bootloader could
be rewritten to use the same toolchain as the Linux kernel but Jeff doesn't want
to for hardware engineer cultural reasons. We have a TODO item to try to come up
with a multiarch toolchain that can work in both modes, but our todo list
runneth over. Note that your FPGA bitstream already has a boot ROM binary in it
so you don't have to rebuild it, and as with the atmel it's again easiest not to.)

And then later I wrote;

> FYI the turtle's got a 2mb spi flash on it (holding the FPGA bitstream) and we
> recently did a bitstream update that makes the last half-megabyte of that SPI
> flash visible to Linux as an mtd, if that's of interest to you. (The change is
> basically just editing the device tree in the boot ROM to mention the flash
> exists and give it a partition layout...) There's some sort of bug with the
> Linux driver that's corrupting writes bigger than 128k at a time, possibly some
> sort of locking issue we haven't had the bandwidth to track down yet. (Works
> fine flashing it form the atmel, but not from Linux. Huh.) I have a TODO item to
> write a flashcp.c for toybox that erases a block, writes it, erases the next
> block, and so on. Instead of doing the "erase all blocks then write all blocks"
> thing that seems to be triggering the bug...

Which I got wrong: it's 4 megabytes of SPI flash.

The new device tree snippet to talk to that hardware is:

                        spiflash at 1 {
                                compatible = "mx25r3235f", "jedec,spi-nor";
                                #address-cells = <1>;
                                #size-cells = <1>;
                                spi-max-frequency = <25000000>;
                                reg = <1>;
                                mode = <0>;

                                fpga_bitstream at 0 {
                                        label = "fpga_bitstream";
                                        reg = <0 0x01e0000>;

                                config at 1 {
                                        label = "tar_etc";
                                        reg = <0x01e0000 0x020000>;

                                partition at 2 {
                                        label = "fatfs";
                                        reg = <0x0200000 0x0e00000>;

I suspect it was already wired up and all the new bitstream added was the extra
device tree snippet to the boot ROM? Yes the boot rom loads a DTB into memory
and sets whichever register it is to point to it...


Looks like r4.

> Feel free to poke the j-core mailing list about any of this, it'd be nice to get
> progress reports there of people doing stuff with Turtle.

And hopefully you're caught up now. :)

Sorry for the delay,


More information about the J-core mailing list