Merge "docs: add detail to assembly language guideline" into integration

docs/process/coding-guidelines.rst

@@ -449,17 +449,20 @@ Generally, prefer code written in C over assembly. Assembly code is less
 portable, harder to understand, maintain and audit security wise. Also, static
 analysis tools generally don't analyze assembly code.
 
-There are, however, legitimate uses of assembly language. These include:
+If specific system-level instructions must be used (like cache maintenance
+operations), please consider using inline assembly. The ``arch_helpers.h`` files
+already define inline functions for a lot of these.
 
-  - Early boot code executed before the C runtime environment is setup.
+There are, however, legitimate uses of assembly language. These are usually
+early boot (eg. cpu reset sequences) and exception handling code before the C
+runtime environment is set up.
 
-  - Exception handling code.
+When writing assembly please note that a wide variety of common instruction
-
+sequences have helper macros in ``asm_macros.S`` which are preferred over
-  - Low-level code where the exact sequence of instructions executed on the CPU
+writing them directly. This is especially important for debugging purposes as
-    matters, such as CPU reset sequences.
+debug symbols must manually be included. Please use the ``func_prologue`` and
-
+``func_epilogue`` macros if you need to use the stack. Also, obeying the
-  - Low-level code where specific system-level instructions must be used, such
+Procedure Call Standard (PCS) is generally recommended.
-    as cache maintenance operations.
 
 Do not use weak functions
 -------------------------