pcs3616 / mvn-rs

mvn-rs

Conjunto de ferramentas de desenvolvimento da Máquina de von Neumann (MVN) da disciplina Sistemas de Programação (System's Programming, PCS3616).

Contém código de processamento de linguagem de montagem e linguagem de máquina, além de as ferramentas montador, ligador e relocator, e uma interface de linha de comando única para acessar as três ferramentas.

Instalação

Um binário da interface de linha de comnado é disponibilizado neste repositório. Ele é compilado com Ubuntu 20.04, e é garantida compatibilidade com Ubuntu 18.04.

Ao baixar o binário, é necessário indicar ao sistema operacional que o arquivo é executável fazendo

$ chmod +x mvn-cli

O binário pode então ser adicionado a algum caminho no $PATH do sistema, que permite acessá-lo como qualquer outro comando de qualquer diretório, ou pode ser adicionado ao diretório em que será usado. Neste segundo caso, é necessário usar uma referência relativa ao caminho do binário no momento da execução, executando de dentro do diretório em que o executável se encontra, por exemplo,

$ ./mvn-cli --help

Uso

Programas exclusivamente com endereços absolutos e sem relacionamento

Para executar programas escritos em linguagem de montagem, eles precisam estar em linguagem de máquina no formato MVN. Essa transposição deve ser feita usando o montador como no exemplo a seguir:

$ mvn-cli assemble -i absoluto.asm > absoluto.mvn

Programas exclusivamente com endereços absolutos e com relacionamento

Caso o seu programa importe ou exporte símbolos, é necessário realizar a montagem seguida de ligação somente daquele programa com a flag --complete

1. A montagem é análoga à do programa absoluto sem relacionamentos, mas é gerado um arquivo INT em vez de um MVN:

   $ mvn-cli assemble -i relacionamentos.mvn > relacionamentos.int

2. Em seguida, o arquivo é passado pelo ligador para remover a tabela de símbolos e gerar o MVN:

   $ mvn-cli link -i relacionamentos.int --complete > relacionamentos.mvn

Programas com endereços relocáveis

O processo é mais complexo com endereços relocáveis. Para demonstrar como usar as ferramentas, vamos assumir que um programa foi desenvolvido com os módulos principal.asm e secundario.asm.

1. Em primeiro lugar, é necessário gerar arquivos INT a partir do montador:

$ mvn-cli assemble -i principal.asm > principal.int
$ mvn-cli assemble -i secundario.asm > secundario.int

2. Em seguida, é necessário ligar os arquivos usando o ligador para gerar um arquivo LIG caso todos os símbolos estejam resolvidos. No lugar da flag --complete, é possível passar a flag --partial para realizar ligação parcial, usada para gerar bibliotecas e não executáveis

   $ mvn-cli link -i principal.int -i secundario.int --complete > programa.lig

3. Por fim, é necessário relocar o programa LIG ligado para gerar um executável MVN com endereços absolutos. É obrigatório passar a base de relocação (--base ou -b), ainda que em geral utilizemos 0.

   $ mvn-cli relocate -i programa.lig --base 0 > programa.mvn

mvn-rs's Issues

Inplementar pseudo instrução $

$ (Reserva de área de dados)

CI runs twice on tags committed to `main`

Due to the way Actions are triggered, one run is executed for the new main commits, and another for the new release tag.

mvn-rs/.github/workflows/release.yml

Lines 13 to 17 in 5bc77a0

	push:
	branches:
	- main
	tags:
	- '*'

Add binary support for Apple Silicon

Since the only release that has been publicaly circulated in the repository is for ubuntu 20.04, other OSes and chip designs are unable to execute the binaries.

Compiling the tool for your specific os has also proven tricky due to the specific environment variables that are used in the CI/CD.

Are there any plans of opening up the compilation steps or introducing new targets?

For the time being I have been using a specific docker image to emulate ubuntu, and could also help out with sharing my Dockerfile and Docker compose, so that others can use their specific oses

Replace `set-output` on release Action

We get this warning fom the Action logs:

The set-output command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/Show less

Implementar pseudo instrução #

'# (Final físico do texto-fonte. Operando=endereço de execução)

Add tests to avoid regression in assembler annotations

We need to add tests to cover the fix in 6af2954.

Introduce warnings into the assembler

The MVN assembly language is simple enough we can come up with situations where emitting a warning might be a good idea. Some I've thought about:

• Warn about the lack of comments in the code
• Warn about numerical operands as argument to normal instructions
• Warn about the use of reserved words as labels
  • #13 makes mnemonics reserved words and does not allow them to be used as labels

Generate warning or error on overwriting of memory regions

During assembly, we could generate an error message if someone writes code in regions of the memory which have already had something written to them before. I'm considering a case like

@ /100
FOO $ /100

; ...
; some other code in between
; ...

@ /150
BAR JP FOO

Not sure if it makes sense to support it though.

A use case that does seem more interesting is emitting warnings (not errors) when linking two source files in which one overwrites part of the memory referenced by the other. Something like

• foo.asm

  & /100
  FOO $ /1
  

• bar.asm

  & /100
  BAR $ /1
  

We do want to support this overwriting since some tests depend on this behaviour, but warning about it could be interesting

Handle invalid mneumonics

Given an instruction (with and without a label), an invalid mneumonic must be detected and an error message must be emitted highlighting the offending mneumonic.

Handling this case should be a straightforward parsing of a nom Err instance, ideally right before creating the Instruction associated with the error.

• Handle error
• Test error handling
• Produce custom error message

Implement modular CLI in all binary crates

@guissalustiano o que você acha? Até quinta eu consigo deixar os outros desse mesmo jeito e resolver a questão dos binários individuais

@guissalustiano eu implementei isso e gostei do resultado. Não vou colocar aqui ainda, mas se quiser dar uma olhada está na branch feat/modular-cli do meu fork: https://github.com/tomaz-suller/mvn-rs/tree/feat/modular-cli

Originally posted by @tomaz-suller in #13 (comment)

Introduce error handling into the assembler

This issue tracks the introduction of some (non-exhaustive) list of errors we may face during execution, mostly due to incorrect user input. This list will be updated in case new possible errors scenarios are found.

Planning

Our first priority should be integrating with nom_locate so we can point error locations using e.g. annotate-snippets, taking heavy inspiration from this post (this is already underway on a different branch stating with 967681e).
Before continuing, it'd be best to decide on how to handle errors (#10).

After that's done, we need to get to the actual errors listed below treated and write proper error messages to each one using some annotation framework. Handling each error basically consists of writing code to:

• Validate the input, either to handle Err returned by a parser or to check on some domain-specific error
• Test that error handling is working properly
• Emit specific, relevant error messages for each error instance

Errors

I decided to sort the possible problems the assembler could face so none went unnoticed.

Programming errors

• Handle nonexistent input, or invalid output path
• Handle incorrect file permissions

Syntactic errors

These are the ones nom should basically throw at us with Errs, so we only need to respond to them with the right error message

• Handle misspelt mneumonics
• Handle use of invalid labels
• Handle invalid immediates (e.g. /G)
• Handle non-ASCII characters outside comments

Logical errors

These should be trickier, with some detectable after parsing the entire file and generating the symbols table

• Handle use of mneumonics as labels
• Handle numeric operands for imports and exports
• Handle symbolic operands for absolute and relocatable position setting
• Handle use of undefined labels

Physical errors

I called "physical" any error related to the structure of the simulator, i.e. if the simulator had more memory or wider words these errors would not occur

• Handle code size exceeding address space
• #19
• Handle over 12 bit immediates for load value instruction
• Handle over 16 bit immediates for any instruction

Implemetar pseudo instrução K

K (Constante. Operando numérico = valor da constante, em hexadecimal)

Duplicated label not throw erros and remove line

LABEL  LV 0
LABEL LV 5

vira

0000 5005

sumindo com a linha e n mandando nenhuma mensagem de erro.

O comportamento desejado deveria ser lançar um erro

Add Dockerfile to make compiler more portable

First suggested by @thife455 in #22 (comment)

Adding instructions to the README on how to pull from the Ubuntu official images and then map the submission directories with -v would be the minimum to get this closed. It would also be good to link to resources explaining what containers are and to the official Docker installation guide.

Ideally, we would write our own (very simple) Dockerfile and publish it somewhere (perhaps as a GitHub package? not sure if Docker is supported) so users could pull directly from our image, with an entry-point to the CLI.

Documentation

We don't have any, so we'd better write some.

We could also consider pointing people to Rust learning resources.

Inplementar pseudo instrução @

@ (Operando numérico: define endereço da instrução seguinte)

Should error handling be eager or lazy?

Since each Line is parsed by all means independently (despite them all making up Lines), and so is each element of Line, errors could be handled lazily: an error in one component of the Line could be generated independently of the others instead of forcing the program to exit immediately.

This would allow more errors to be detected on a single assembler run, but could become overwhelming pretty quickly. It also basically forces all error handling into main.rs instead of into the modules where the errors occur. And it requires greater care in considering whether to throw a nom::Err::Error (for recoverable errors) or nom::Err::Failure (for irrecoverable ones).

Replace some `panic!` with proper error treatment

Esses são os casos de panic! que envolvem erro de entrada do usuário, não bug do código. Seria bom se a gente conseguisse retornar uma menasgem de erro mais bonita do que a padrão do Rust, que pode acabar confundindo os alunos.

Estou marcando isso mais pra lembrar que isso existe do que pra gente mexer nisso agora.

Originally posted by @tomaz-suller in #13 (review)

Errors return 0 exit code

Returning OK exit code does not allow some tools (such as make) to stop early in case of failure.

Every CLI component should return a non-zero exit code before exiting on printing an error.

CI fails from lack of `.env` we want to keep secret

CI fails because the .env file we want to keep secret is not there, and even then there's no way to make it openly available. @guissalustiano any suggestions? I see we can either rewrite all tests to reference .env (which will be a pain) or use those GitHub Secrets somehow in our CI, which I assume you know better than I do

Originally posted by @tomaz-suller in #13 (comment)

"Montador" em inglês é "assembler"

... e não "mounter".

Faz mais sentido abrir a issue do que simplesmente mudar o nome do repo porque a gente precisaria (até onde eu sei) mudar nos nossos repositórios locais também o nome do remote.