Turn r68k into a lib

[emoon]

Now that all instructions for 68k has been implemented (right?) it would be great to turn this into a proper Rust lib/crate so it can be used in other projects.

[marhel]

As the README says; "all instructions are implemented and verified against Musashi, but infrastrucure such as interrupts and host callbacks are yet to be implemented, and it's therefore not quite usable at this point."

But, sure, if you do feel it's usable then we could put some effort into turning it into a form more easily consumed. What are your suggestions?

[emoon]

I would say it's still useable in a limited context (you have data setup and want to run some 68k on that limited set)

Things I think should be fixed

• all qc code should be moved in under test cfg so when build the create for regular usage it not compiled
• if Musashi should still be around it needs to be compiled from source as its Mac only
• create should be switch from bin to lib
• some basic examples of using it with setting up some memory, a simple program that can be executed and to show modified/mem/registers and cycle count

[marhel]

Yes, QC should be a dev-dependency only.

I haven't tested on Windows, but I guess one could add a Windows-build of the Musashi lib as well? But setting up compilation from source would be even better (like you did with Capstone, I didn't know cargo could help build C programs as well).

The crate should be a lib crate, agreed, and cargo have some "example program" support for libs we could use, right?

So in short, I agree with everything you said :)

[emoon]

Problem with including a binary for Windows is that if someone is using it on Linux (or some other OS) it won't work so better to bulid from source. Musashi does some trickery with generating new C code from a description but that is possible to do with build.rs as well but I'm not sure if it's possible to only do it for dev-only (otherwise you really endup with two emulators where only one is really used)

For examples yes. What you do is to add a directory examples and then you can add examples souch as examples/basic.rs basic.rs will now use r68k as a regular external crate. To test it you write

cargo run --example basic

[marhel]

Oh, but couldn't we just generate the C code once with the custom Musashi code generator, and include the generated file, instead of actually generating the code each time? We should point back to the Musashi-repo in any case, and ensure the process of re-generating is documented.

I think cargos "--example" feature is a really good supporting feature for library authors (and users), haven't seen that elsewhere.

[emoon]

Build the generater and just run it is fairly simple so I don't think it such a big issue really. The generation isn't what takes the time it's actually compiling the code that is a bit slow (few sec depending on your system) but I guess we only need to generate the 000 one also while Musashi by default does 020+ also.

Yeah --example is great. It allows you to really show of how the library is supposed to be used. Also another thing is when you document code in Rust (and use cargo to generate it) the code will be compiled and checked so your examples will always work with the given code you have.

[marhel]

If you've got some time to kill, you could take a look at the library branch (https://github.com/marhel/r68k/tree/library) which tries to move r68k over to a library. It's incomplete still, but contributions towards a better user experience are welcome. I'm thinking of adding an example that runs 10M cycles worth of dhrystone, or something like that, as a performance baseline. (bench is still not in stable, right?)

[marhel]

Improvements have been made on this

• The emulation part of r68k is now implemented as a lib in the emu folder of the repo
• Emulation itself is mostly complete (see README)
• Musashi, Quickcheck, rand, libc and itertools are now dev dependencies (and are not needed or included in a release build)
• A few examples have been added (however, much more documentation and a more complete example is needed)

Musashi usage being Mac only has not been addressed.

[emoon]

Would it be possible to publish the different parts (or one crate with opt-in on what you need) on crates.io? Would make it easier to use in projects then :)

[marhel]

Absolutely. I'm getting there.

I'm just trying to get it into a state where I don't have to make excuses for the state it is in 😄. I want to make memory and interrupt controllers pluggable, and add some documentation.

[emoon]

Cool :)

[sethm]

Bump! I'd love to use this library in a Rust project I'm working on that requires an emulated MC68000 core with a fairly bizarre ROM and RAM map. Musashi/r68k seems by far the best tool for the job.

If I can help in any way, ping me!

[marhel]

Hi!

I'd love if r68k would be useful for you! There's is some refactoring work I've initiated a while ago that's present in the core-trait branch, which turns r68k into a lib, and Core into a trait, allowing a Core impl to be generic over the Memory and Interrupt Controller implementations. I wasn't at all experienced with ideomatic Rust design when I started this project, so I initially hardcoded some test-optimized "hardware" directly into the struct to get started, and I'm almost done paying off that particular technical debt.

With these changes, the main hurdle for you I guess would be the general lack of documentation. But I had already planned to do more docs before publishing a r68k crate, and I'm willing to do some documentation "on demand" here to help you along, because it would help me finally reach 1.0 quality.

So, if you're willing to help out, I'd suggest starting by taking a look at the benchmark code which illustrates the following;

• the proper way to set up a ConfiguredCore with some memory and an interrupt controller
• a primitive way to load some instructions into memory
• how to use execute_with_state to emulate execution of a given number of clock cycles
• how to use the exception_callback to track and/or handle exceptions and interrupts

and then fire away questions either here, or by opening up new issues, and I'll try to help you out.

Since r68k isn't yet a published crate, you'll need to tell Cargo your code have a github dependency by adding r68k-emu to your dependencies like this;

[dependencies]
r68k-emu = { git = "https://github.com/marhel/r68k", branch = "core-trait" }

[sethm]

Hi Marhel, just wanted to say thanks so much for this write-up. It's really great that you'd be willing to help like this. I've been very busy with my day job, but this week I would like to spend some time in the evenings getting a skeleton project built around r68k.