-
Notifications
You must be signed in to change notification settings - Fork 220
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API for running RARS from the command line #13
Comments
Making a minimal api per your suggestion would be quite easy (I think). However, I would like to go a little bit beyond the minimum. But I haven't come up with a good idea to have a nice, flexible api that doesn't require understanding the internals of RARS. Here are some requirements that I would like to hit:
I think all of the above requirements can be met technically without much work, but I don't know how to make that into a clear interface. Its possible the STDIN and STDOUT redirecting may take a little bit of extra work, but I think thats probably worth it. Additionally, while thinking about this I had some requirements that would be nice to have (and would help the project as a whole), but are not easy technically.
|
Everything you propose sounds eminently doable. Without knowing much about RARS' internals, I can imagine that exposing such an API would also be a good chance to refactor and clean up the code. Naturally, refactoring can introduce new errors, so I recommend thinking about how the old code can be used as a testing oracle for the refactored code. |
I have come up with a design I am pretty happy with. The bulk of the interface would be in a Program class as follows:
An example usage might be:
This api requires modifying the SystemIO to allow STDIN and STDOUT to be set and a small modification to Memory allowing it to be reset to a given state easily. Additionally, a small modification to how assembling works would allow a raw string to serve as source code. I can also imagine that there would be some streamlined methods on top of this that makes it easy to make a simple pass/fail per testcase. But I think this interface makes it pretty easy to drive the simulator however you want and wraps up the internals nicely. |
Looks good. Is it possible to get register content after termination? |
PS Would it be difficult to return the number of steps taken upon termination? What about other profiling data, like memory used, maximal height of stack (I known that RISC-V doesn't have an explicit stack pointer, so this really amounts to returning the range of values (min, max) a register attains during execution, or at least register X2)? It's not vital at all for my use case, but if such facilities existed, I could give students more interesting feedback. (OTOH, there is always the danger of over-engineering ...) |
With the proposed design thats pretty easy. It would be something like:
Instead of the
Yes, it would be more difficult. However, I looked into it a bit while working on the api thus far and I think I have an idea for adding a way for a bunch of information to come out of the simulator. For the time being, I don't want to commit to adding that feature which is about the same difficulty as finishing the rest of the planned interface. I believe it would be easy to add in to the interface in the future. |
Fair enough. Keeping things minimal is a good software engineering technique. As to |
One of the reasons is that string lookup already has to exist for the assembler. With that in mind, adding enums to represent each would make it more typesafe, but doesn't provide much safety as there isn't any way in a standard compiler to ensure all members are used once in a switch or similar construct. So when adding access by enum the possibility there is the possibility a bug is introduced. Access by explicit method has a similar possibility of messing up when writing as you would need to assign each register to both an array for string searching and whatever mechanism you are using to make the methods work. Additionally, that would result in a ton of boiler plate code. The current system allows for easy code reuse (RegisterBlock is used to back the normal, floating point and control and status registers). And the only place the access by string is used is in system calls. If you are testing the system calls, there is no possibility of something happening that the type system could detect. TLDR; mechanisms to make it more type checked cost lines of code with the only benefit being that issues can be caught at compile time rather than runtime (in which case with any testing, they will be caught). |
ic, register logging, memory logging and dump sections were all broken by 07581f9 . The global state for the program is now held inside of a program object instead of globally accessible, so logging gets the zeroed memoery and registers rather than the chnaged ones. I noticed this while working on documentation for the commandline. The fix is to pass the program object into the logging functions so they can use local references to the data rather than reference Globals.memory or RegisterFile. Dump has not been fixed yet as that is going to touch more files. Obviously #13 is related, and this also shows how to get lines executed as part of the api. A bonus of this is that it removes the jank way ic used to be calculated.
For anyone on this thread who's looking for a currently-working example usage, here's a fully-worked API usage example that compiles against RARS 345c17b.
Usage looks as such with input file
|
@amoe, thanks for adding an example. Having a readable example should definitely be helpful to other people trying to use the API. It should also be noted though that RARS uses the API internally for testing and cli functionality. Both of those are a little complex, but demonstrate how most of the features of it can be used. Because there is very little documentation on how to effectively use the API, I am also happy to answer questions. |
It would be nice to have an API that makes it possible to run RARS within other programs. Maybe a method with a signature like so:
Here the input string is the RISC-V assembly. The type RISC_V_State can be given in various ways. Minimally, the state should provide something along the lines of:
Clearly all this is available internally already, so it'd just be a matter of creating a suitable API.
The text was updated successfully, but these errors were encountered: