From 2ce78bff8b7c214b6f1c8ef46fa966afd14c0aa2 Mon Sep 17 00:00:00 2001 From: Boyan Karatotev Date: Fri, 24 Mar 2023 13:09:33 +0000 Subject: [PATCH] docs: add detail to assembly language guideline Assembly language is rarely required and when it is, there are a lot of helpers available to reduce the amount needed. Update the guidelines to give pointers to them. Signed-off-by: Boyan Karatotev Change-Id: Ic484e4ba57242594c351a9185ecb625d6e5dc223 --- docs/process/coding-guidelines.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index 13fb7cbaf..97303905f 100644 --- a/docs/process/coding-guidelines.rst +++ b/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. - - - Low-level code where the exact sequence of instructions executed on the CPU - matters, such as CPU reset sequences. - - - Low-level code where specific system-level instructions must be used, such - as cache maintenance operations. +When writing assembly please note that a wide variety of common instruction +sequences have helper macros in ``asm_macros.S`` which are preferred over +writing them directly. This is especially important for debugging purposes as +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 +Procedure Call Standard (PCS) is generally recommended. Do not use weak functions -------------------------