Merge pull request #650 from rlopez3d/main

Pull request for new Learning Path Memory Tagging Extension on Google pixel 8.

Author: pareenaverma

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/_index.md

@@ -0,0 +1,37 @@
+---
+title: Memory Tagging Extension on Google Pixel 8
+
+minutes_to_complete: 10
+
+who_is_this_for: This is an introductory topic for developers interested in learning how to enable Arm Memory Tagging Extension (MTE) on Google Pixel 8 smartphone and how to access a memory bug report.
+
+learning_objectives: 
+    - Enable MTE on your Google Pixel 8 smartphone
+    - Understand how MTE works and learn how to make an application crash when it encounters a memory bug
+    - Access the memory bug report
+    - Interpret the memory bug report
+
+prerequisites:
+    - A Google Pixel 8 smartphone
+    - A USB cable to connect your Google Pixel 8 to your desktop machine
+    - Android Debug Bridge (adb) installed on your device. Follow the steps in https://developer.android.com/tools/adb to install Android SDK Platform Tools. The adb tool is included in this package.
+
+author_primary: Roberto Lopez Mendez
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Cortex-A
+tools_software_languages:
+    - Memory Bug Report
+operatingsystems:
+    - Android
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/_next-steps.md

@@ -0,0 +1,32 @@
+---
+next_step_guidance: >
+    If you are interested in learning more about MTE, follow this learning path: 
+
+recommended_path: "/learning-paths/smartphones-and-mobile/mte/"
+
+further_reading:
+    - resource:
+        title: MTE User Guide for Android OS
+        link: https://developer.arm.com/documentation/108035/latest/
+        type: documentation
+    - resource:
+        title: Arm Memory Tagging Extension
+        link: https://developer.android.com/ndk/guides/arm-mte
+        type: website
+    - resource:
+        title: AArch64 TAGGED ADDRESS ABI
+        link: https://www.kernel.org/doc/Documentation/arm64/tagged-address-abi.rst
+        type: documentation
+    - resource:
+        title: Enhanced Security Through MTE
+        link: https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/enhanced-security-through-mte
+        type: documentation
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/_review.md

@@ -0,0 +1,44 @@
+---
+review:
+    - questions:
+        question: >
+            Can MTE be enabled on my Google Pixel 8?
+        answers:
+            - "Yes"
+            - "No"
+        correct_answer: 1                    
+        explanation: >
+            MTE option is part of Developer options. Developer options need to be enabled first on your Google Pixel 8 phone to access MTE.
+
+    - questions:
+        question: >
+            Which of the statements below is false?
+        answers:
+            - MTE working principle is based on a Lock and Key model.
+            - Tagging memory implements the lock.
+            - Pointers are modified to contain the key.
+            - At runtime the CPU checks that the pointer and the metadata tags match. If so, the application crashes in any device.
+        correct_answer: 4                   
+        explanation: >
+            At runtime the CPU checks that the pointer and the metadata tags match, on each load and store. Android apps that incorrectly store information in the top byte of the pointer are guaranteed to break on an MTE-enabled device.
+               
+    - questions:
+        question: >
+            Which of the statements below is true?
+        answers:
+            - The bug report is automatically generated everytime the application crashes.
+            - You need to trigger the creation of the bug report using the Bug report option in Developer options.
+            - The bug report is a single file you can visualize directly in our phone.            
+        correct_answer: 2          
+        explanation: >
+           You have to tap Bug report option in Developer options to capture the bug report.
+
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+title: "Review"                 # Always the same title
+weight: 20                      # Set to always be larger than the content in this path
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+---

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/example-picture.png

@@ -0,0 +1,31 @@
+---
+title: Enabling MTE on Pixel 8
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Enabling Memory Tagging Extension on Pixel 8 
+
+Google Pixel 8 is the first smartphone supporting MTE out-of-the-box.
+To enable MTE on your Pixel 8 you first need to enable Developer options.
+
+Follow the steps below to enable Developer Options on your Pixel 8:
+* On your device, find the Build number option in Settings -> About phone -> Build number.
+
+* Tap the Build number option seven times until you see the message "You are now a developer!" This enables Developer options on your device.
+
+* Return to the previous screen and tap the System option. The just enabled Developer options will be at the bottom. 
+
+[This is a comment that will be hidden.]: # 
+
+MTE is now available as part of Developer options. Tap on Developer options and next tap on Memory Tagging Extension option. You will see in your screen the picture below:
+
+![alt-text-2](pictures/02_mte_option.png "MTE option")
+
+
+
+
+
+

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/how-to-1.md

@@ -0,0 +1,21 @@
+---
+title: Understanding MTE
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Memory Tagging Extension: working principle
+
+According to Google, memory bugs are the top contributor to Android security vulnerabilities. Memory bugs are also responsible for higher lifetime costs in software development and poor user experience.
+Additionally, developers know finding memory bugs can be difficult.
+
+The Memory Tagging Extension developed by Google and Arm is aimed at providing developers with the right tool to easily detect memory bugs, and as a result help improve robustness and security of Android apps.
+
+The MTE working principle is based on a Lock and Key model. Memory locations are tagged by adding four bits of metadata to each 16 bytes of physical memory. Tagging memory implements the lock. Pointers, and therefore virtual addresses, are modified to contain the key.
+In order to implement the key bits without requiring larger pointers, MTE uses the Top Byte Ignore feature of the Armv8-A Architecture. This allows the top byte to store metadata. In MTE four bits of the top byte are used to provide the key. 
+
+At runtime the CPU checks that the pointer and the metadata tags match on each load and store. Android apps that incorrectly store information in the top byte of the pointer are guaranteed to break on an MTE-enabled device. 
+
+![alt-text-2](pictures/03_mte_lock_and_key_model.png "MTE Lock and Key underlying model.")

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/how-to-2.md

@@ -0,0 +1,36 @@
+---
+title: Testing MTE
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## MTE Test Application
+
+`MTE_test.apk` is an application that implements the most common types of memory bugs. By pressing any buttons on this application shown below, you can execute code containing a memory bug. If MTE is enabled on your device, MTE will detect the memory violation and make the application crash. You can then retrieve a bug report. This report contains useful information to identify the cause of the crash and where it happened.
+
+![alt-text-2](pictures/04_mte_test_app.png "MTE test application implementing most comon memory bugs.")
+
+## Installing MTE Test Application
+
+Follow the steps below to install `MTE_test.apk` on your Google Pixel 8.
+
+
+* Navigate to [this repository](https://github.com/rlopez3d/mte_test_app). Open the "apk" folder and click on "MTE_test.apk" file. Use the download icon on the right to download the apk to your desktop machine.
+
+* Connect your Pixel 8 to the USB port.
+
+* Open a console and change directory `cd` to where you downloaded the apk.
+
+* Execute the command `adb devices`. The console should display the list of atached devices.
+
+* Execute the command `adb install MTE_test.apk`. The console should display that the apk has been installed succesfully.
+
+* You should see the Android icon of the app with the name `MTE_test` on your phone.
+
+
+
+
+
+

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/how-to-3.md

@@ -0,0 +1,32 @@
+---
+title: Creating the Bug Report
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Capturing the Bug Report
+A bug report contains device logs, stack traces, and other diagnostic information to help you find and fix bugs in your application. If MTE is enabled on the device, the bug report will contain specific additional information about the memory bug. To capture a bug report on your Google Pixel 8, use the Bug report option available in Developer options menu, as shown below.
+
+![alt-text-2](pictures/05_bug_report_option.png "Bug report option in Developer options menu.")
+
+Tap Bug report option to capture the bug report. Leave the Interactive report option selected on the next screen and tap Report at the bottom.
+
+![alt-text-2](pictures/06_creating_bug_report.png "Creating the bug report.")
+
+At this point the bug report generation starts. You can see the progress of the bug report generation by sliding down the notification panel as shown below. By tapping on the drop-down icon on the right you can set a name for the bug report, and add a useful comment that will help you identify it later.   
+
+![alt-text-2](pictures/07_bug_report_is_being_generated.png "Bug report is being generated.")
+
+Once the bug report generation has completed, you can share it by tapping on the notification.
+
+![alt-text-2](pictures/08_bug_report_captured.png "Bug report is captured.")
+
+The bug report is a big text file containing useful information about the cause of the crash and where it happened. The phone screen is not best suited for viewing this file. It is better to do it in your desktop machine on a big screen. You can send the report using any of the available options on your phone. 
+
+![alt-text-2](pictures/09_sharing_bug_report.png "Sharing the bug report.")
+
+
+YOUR CONTENT GOES HERE
+

content/learning-paths/smartphones-and-mobile/mte_on_pixel8/how-to-4.md

@@ -0,0 +1,47 @@
+---
+title: The Bug Report
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Bug Report Content
+The bug report is a zip file. Once you have it on your desktop machine, you need to decompress it to access the content. After unzipping the file, you will see the folder structure below and the bug report txt file. Husky is the code name for Gooogle Pixel 8 Pro and it is used when generating the name of the bug report file.
+
+![alt-text-2](pictures/10_unzipped_bug_report.png "Unzipped bug report file.")
+
+More detailed information is written to a tombstone file located in `FS/data/tombstones` folder as shown below:
+
+![alt-text-2](pictures/11_tombstone_filepath_in_bug_report.png "Tombstone file in bug report.")
+
+## Interpreting the Bug Report
+
+The bug report contains diagnostic output for system services, error logs, and system message logs (logcat). The system messages include stack traces when the device throws an error. When running MTE in SYNC mode, the Android allocator records stack traces for all allocations and deallocations and uses them to produce the bug report.
+
+When a tag mismatch is encountered, the processor aborts execution immediately and terminates the process with SIGSEGV, using code SEGV_MTESERR, logging full information about the memory access and the faulting address. In addition, the crash report shows the process ID, the thread ID, and the cause of the crash.
+
+![alt-text-2](pictures/12_header_of_tombstone_file.png "Header of tombstone file.")
+
+The line comencing with "signal 11 (SIGSEGV)" shows that an abort signal was received, with code SEGV_MTESERR, caused by an access to memory address `0x0b000073c323d595`.
+
+More detailed information is written to the tombstone file. It contains detailed data about the crashed process, including the following:
+* Stack traces for all the threads in the crashed process, including the thread that caught the signal
+* A full memory map
+* A list of all open file descriptors
+
+The tombstone file includes an explanation of each memory error, such as use-after-free, or buffer overflow, and the stack traces of the relevant memory events. These reports provide more contextual information and make bugs easier to trace and fix.
+
+![alt-text-2](pictures/13_tombstone_cause_of_memory_bug.png "Tombstone - cause of memory bug and output from the unwinder.")
+
+For more information about how to interpret bug reports, refer to the following Android documentation resources:
+* [MTE User Guide for Android OS](https://developer.arm.com/documentation/108035/latest/) 
+* [Android OS Documentation: Diagnosing Native Crashes](https://source.android.com/docs/core/tests/debug/native-crash)
+* [Android OS Documentation: Debugging Native Android Platform Code](https://source.android.com/docs/core/tests/debug)
+
+
+
+
+
+YOUR CONTENT GOES HERE
+