diff --git a/README.md b/README.md index d5b0361..bd51784 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,24 @@ [![Build Status](https://travis-ci.org/exercism/arm64-assembly.svg?branch=master)](https://travis-ci.org/exercism/arm64-assembly) Exercism exercises in ARM64 Assembly. + +## Assembler + +GNU Assembler (gas) is used for this track. + +## Testing + +Unity is a simple unit testing framework for C used by this track. +Using a framework written in C instead of assembly language is easier to understand. +It also shows how parameters are passed when calling assembly routines from C. + +## Variant and Calling Conventions + +This is probably going to use the ARMv8.0-A profile which is a good default. +This track is also probably going to use the ARM default calling convention to spare mentors from trouble. + +## Contributing Guide + +Please see the [contributing guide][contributing-guide] + +[contributing-guide]: https://github.com/exercism/x-api/blob/master/CONTRIBUTING.md#the-exercise-data diff --git a/config.json b/config.json index 3cf6df1..759a9c9 100644 --- a/config.json +++ b/config.json @@ -48,5 +48,18 @@ }, "concepts": [], "key_features": [], - "tags": [] + "tags": [ + "paradigm/imperative", + "paradigm/procedural", + "typing/static", + "typing/weak", + "execution_mode/compiled", + "platform/android", + "platform/ios", + "platform/mac", + "platform/linux", + "runtime/standalone_executable", + "used_for/embedded_systems", + "used_for/mobile" + ] } diff --git a/docs/ABOUT.md b/docs/ABOUT.md index 79ac4c2..a5b5949 100644 --- a/docs/ABOUT.md +++ b/docs/ABOUT.md @@ -1,2 +1,7 @@ # About +ARM64/AArch64 assembly is the 64-bit version of the ARM instruction set. +It is based on the ARMv7 instruction set, which is in turn loosely based off the legacy ARM Classic instruction sets. + +This track involves programming in ARM64 assembly language, assembled and run on a cross-platform simulator. + diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 4026317..f2b377a 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,2 +1,13 @@ # Installation +Install the essential build tools, the QEMU emulator, and the GCC ARM64 cross-toolchain to test your code. + +```shell +sudo apt install build-essential qemu-user qemu-user-static binutils-aarch64-linux-gnu gcc-aarch64-linux-gnu +``` + +The makefile in the exercise directory should be able to handle the rest. + +## Special note for Windows users + +Use Windows Subsystem for Linux 2 with an Ubuntu image to do the same steps listed above. \ No newline at end of file diff --git a/docs/LEARNING.md b/docs/LEARNING.md index c39c2a2..2b668d0 100644 --- a/docs/LEARNING.md +++ b/docs/LEARNING.md @@ -1,2 +1,13 @@ # Learning +ARM64 assembly is a simple assembly language. +You might be able to start off with [a reference card][reference-card]. + +ARM also provides [digital reference][official-reference] on the ARM64 (AArch64/ARMv8) architecture. + +We hope you enjoy learning ARM assembly and working through the exercises. + +This is a gateway to getting to know your phone or ARM64 based development hardware (the more recent Raspberry Pi models are an example). + +[reference-card]: https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf +[official-reference]: https://developer.arm.com/documentation diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index 06f84ec..79b8127 100644 --- a/docs/RESOURCES.md +++ b/docs/RESOURCES.md @@ -1,2 +1,12 @@ # Resources +- [ARM64 reference card][reference-card] +- [Official ARM documentation][official-reference] +- [The GAS Manual][gas-manual] +- [The GAS AArch64 Specifics Section][gas-aarch64-specifics] + + +[reference-card]: https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf +[official-reference]: https://developer.arm.com/documentation +[gas-manual]: https://sourceware.org/binutils/docs/as/ +[gas-aarch64-specifics]: https://sourceware.org/binutils/docs/as/AArch64_002dDependent.html#AArch64_002dDependent diff --git a/docs/SNIPPET.txt b/docs/SNIPPET.txt new file mode 100644 index 0000000..bed5537 --- /dev/null +++ b/docs/SNIPPET.txt @@ -0,0 +1,13 @@ +.section .rodata +msg: .string "Assembly is awesome!\n" + +.text +.global main +main: + adrp x0, msg + add x0, x0, :lo12:msg + stp x29, x30, [sp] + bl printf + ldp x29, x30, [sp] + mov x0, #0 + ret diff --git a/docs/TESTS.md b/docs/TESTS.md index 5932b40..3912fe5 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -1,2 +1,17 @@ # Tests +## Running Tests + +To run the tests, execute the following command: + +```bash +make +``` + +## Solving the exercise + +Solving an exercise means making all its tests pass. +By default, only one test (the first one) is executed when you run the tests. +This is intentional, as it allows you to focus on just making that one test pass. +Once it passes, you can enable the next test by removing the `TEST_IGNORE()` line. +When all tests have been enabled and your implementation makes them all pass, you'll have solved the exercise! diff --git a/docs/config.json b/docs/config.json index 6f9406d..b901bf8 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1,3 +1,33 @@ + { - "docs": [] + "docs": [ + { + "uuid": "3625b605-b556-4bcf-87da-77f06e493deb", + "slug": "installation", + "path": "docs/INSTALLATION.md", + "title": "Installing ARM64 Assembly locally", + "blurb": "Learn how to install ARM64 Assembly locally to solve Exercism's exercises on your own machine" + }, + { + "uuid": "3a09769c-f5ad-4e3a-912a-b06ba6cf604b", + "slug": "learning", + "path": "docs/LEARNING.md", + "title": "How to learn ARM64 Assembly", + "blurb": "An overview of how to get started from scratch with ARM64 Assembly" + }, + { + "uuid": "292b3fa9-45dd-43ec-8528-d3bf442200a4", + "slug": "tests", + "path": "docs/TESTS.md", + "title": "Testing on the ARM64 Assembly track", + "blurb": "Learn how to test your ARM64 Assembly exercises on Exercism" + }, + { + "uuid": "d4066012-de8c-4c28-89eb-f68dbd075444", + "slug": "resources", + "path": "docs/RESOURCES.md", + "title": "Useful ARM64 Assembly resources", + "blurb": "A collection of useful resources to help you master ARM64 Assembly" + } + ] } diff --git a/exercises/practice/hello-world/Makefile b/exercises/practice/hello-world/Makefile index 3813116..a69f16f 100644 --- a/exercises/practice/hello-world/Makefile +++ b/exercises/practice/hello-world/Makefile @@ -1,4 +1,5 @@ -AS = as +AS = aarch64-linux-gnu-as +CC = aarch64-linux-gnu-gcc CFLAGS = -g -Wall -Wextra -pedantic -Werror LDFLAGS = @@ -15,7 +16,7 @@ ALL_OBJS = $(filter-out example.o,$(C_OBJS) $(AS_OBJS) vendor/unity.o) CC_CMD = $(CC) $(ALL_CFLAGS) -c -o $@ $< all: tests - @./$< + qemu-aarch64 -L /usr/aarch64-linux-gnu ./$< tests: $(ALL_OBJS) @$(CC) $(ALL_CFLAGS) $(ALL_LDFLAGS) -o $@ $(ALL_OBJS) diff --git a/exercises/shared/.docs/help.md b/exercises/shared/.docs/help.md new file mode 100644 index 0000000..827205c --- /dev/null +++ b/exercises/shared/.docs/help.md @@ -0,0 +1,9 @@ +# Help + +To get help if you're having trouble, you can use one of the following resources: + +- [ARM64 reference card](https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf) +- [Official ARM documentation](https://developer.arm.com/documentation) +- [The GAS Manual](https://sourceware.org/binutils/docs/as/) +- [The GAS AArch64 Specifics Section](https://sourceware.org/binutils/docs/as/AArch64_002dDependent.html#AArch64_002dDependent) +- [StackOverflow](http://stackoverflow.com) can be used to search for your problem and see if it has been answered already. You can also ask and answer questions. diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md new file mode 100644 index 0000000..d0a835d --- /dev/null +++ b/exercises/shared/.docs/tests.md @@ -0,0 +1,15 @@ +# Tests + +To run the tests, execute the following command: + +```bash +make +``` + +## Skipped tests + +Solving an exercise means making all its tests pass. +By default, only one test (the first one) is executed when you run the tests. +This is intentional, as it allows you to focus on just making that one test pass. +Once it passes, you can enable the next test by removing the `TEST_IGNORE()` line. +When all tests have been enabled and your implementation makes them all pass, you'll have solved the exercise!