1.. _asm_coding_guidelines:
2
3Assembly Language Coding Guidelines
4###################################
5
6.. contents::
7   :local:
8
9
10General
11*******
12
13ASM-GN-01: One address shall not be declared by two labels
14==========================================================
15
16Compliant example::
17
18    asm_showcase_1:
19            movl    $0x1, %eax
20
21.. rst-class:: non-compliant-code
22
23   Non-compliant example::
24
25       asm_showcase_1:
26       asm_showcase_2:
27               movl    $0x1, %eax
28
29
30ASM-GN-02: Names reserved for use by the assembler shall not be used for any other purpose
31==========================================================================================
32
33Names defined by developers shall not be the same as an assembler directive,
34instruction prefix, instruction mnemonic, or register name.
35
36Compliant example::
37
38    asm_showcase_1:
39            movl    $0x1, %eax
40
41    asm_showcase_2:
42            movl    $0x2, %eax
43
44    asm_showcase_3:
45            movl    $0x3, %eax
46
47.. rst-class:: non-compliant-code
48
49   Non-compliant example::
50
51       text:
52               movl    $0x1, %eax
53
54       mov:
55               movl    $0x2, %eax
56
57       eax:
58               movl    $0x3, %eax
59
60
61ASM-GN-03: All declared labels shall be used
62============================================
63
64Otherwise, the label shall be removed.
65
66Compliant example::
67
68    asm_showcase_1:
69            movl    $0x1, %eax
70            jmp     asm_showcase_2
71
72    /* do something */
73
74    asm_showcase_2:
75            movl    $0x2, %eax
76
77.. rst-class:: non-compliant-code
78
79   Non-compliant example::
80
81       asm_showcase_1:
82               movl    $0x1, %eax
83
84       /*
85        * 'asm_showcase_2' is not used anywhere, including
86        *  all C source/header files and Assembly files.
87        */
88       asm_showcase_2:
89               movl    $0x2, %eax
90
91
92ASM-GN-04: Magic numbers shall be used with restrictions
93========================================================
94
95Only the following cases shall be allowed:
96
97a) The magic number is defined as a MACRO with a name clearly indicating its
98   meaning.
99b) The meaning of the magic number is clearly documented in the comments before
100   its usage.
101c) The meaning of the magic number is straightforward in the specific context.
102
103Compliant example::
104
105    .section .data
106    showcase_data:
107            /* 0xff000000 means <something> */
108            .long   0xff000000
109
110.. rst-class:: non-compliant-code
111
112   Non-compliant example::
113
114       .section .data
115       showcase_data:
116               .long   0xff000000
117
118
119ASM-GN-05: Parentheses shall be used to set the operator precedence explicitly
120==============================================================================
121
122Compliant example::
123
124    .section .data
125    showcase_data:
126            /* 0x1234 means <something> */
127            .long   0x1234 * (0x1234 >> 2)
128
129.. rst-class:: non-compliant-code
130
131   Non-compliant example::
132
133       .section .data
134       showcase_data:
135               /* 0x1234 means <something> */
136               .long   0x1234 * 0x1234 >> 2
137
138
139ASM-GN-06: .end directive statement shall be the last statement in an Assembly file
140===================================================================================
141
142This rule applies only to the Assembly file that uses the ``.end`` directive.
143The ``.end`` directive shall be the last statement in this case. All
144statements past the ``.end`` directive will not be processed by the assembler.
145
146Compliant example::
147
148    #include <types.h>
149    #include <spinlock.h>
150
151    .macro asm_showcase_mov
152            movl    $0x1, %eax
153    .endm
154
155    .end
156
157.. rst-class:: non-compliant-code
158
159   Non-compliant example::
160
161       #include <types.h>
162
163       .end
164
165       #include <spinlock.h>
166
167       .macro asm_showcase_mov
168               movl    $0x1, %eax
169       .endm
170
171
172ASM-GN-07: Infinite loop shall not exist
173========================================
174
175Compliant example::
176
177    asm_showcase_1:
178            movl    $0x1, %eax
179            jmp     asm_showcase_2
180
181    /* do something */
182
183    asm_showcase_2:
184            movl    $0x2, %eax
185
186.. rst-class:: non-compliant-code
187
188   Non-compliant example::
189
190       asm_showcase_1:
191               movl    $0x1, %eax
192               jmp     asm_showcase_1
193
194
195ASM-GN-08: All code shall be reachable
196======================================
197
198Compliant example::
199
200    asm_showcase:
201            movl    %ebx, %eax
202            test    $0x400, %eax
203            jne     asm_test
204            movl    $0x2, %eax
205            movl    $0x3, %eax
206
207    asm_test:
208            movl    $0x6, %eax
209
210.. rst-class:: non-compliant-code
211
212   Non-compliant example::
213
214       asm_showcase:
215               movl    %ebx, %eax
216               jmp     asm_test
217               /* the following two lines have no chance to be executed */
218               movl    $0x2, %eax
219               movl    $0x3, %eax
220
221       asm_test:
222               movl    $0x6, %eax
223
224
225ASM-GN-09: Far jump shall be used with restrictions
226===================================================
227
228Jumping to an instruction located in a different segment shall be used only
229for the following two cases:
230
231a) Code bit changes, such as change from 32-bit mode to 64-bit mode.
232b) System resumes from S3. In this case, Global Descriptor Table (GDT) is set by
233   Bootloader/BIOS and far jump has to be used to correct the Code Segment (CS).
234
235Compliant example::
236
237    .code32
238    execution_32:
239            /*
240             * do something in 32-bit mode,
241             * then,
242             * perform a far jump to start executing in 64-bit mode
243             */
244            ljmp    $0x0008, $execution_64_2
245
246    .code64
247    execution_64_1:
248            /* do something in 64-bit mode */
249
250    execution_64_2:
251            /* do something in 64-bit mode */
252
253.. rst-class:: non-compliant-code
254
255   Non-compliant example::
256
257       .data
258       asm_showcase_data:
259               .word   0x0008
260
261       .code32
262       execution_32:
263               /* do something in 32-bit mode */
264               ljmp    $0x0008, $asm_showcase_data
265
266
267ASM-GN-10: Assembler directives shall be used with restrictions
268===============================================================
269
270Usage of the assembler directive refers to the GNU assembler ``as`` user
271manual. Only the following assembler directives may be used:
272
2731) ``.align``
2742) ``.end``
2753) ``.extern``
2764) repeat related directives, including ``.rept`` and ``.endr``
2775) global related directives, including ``.global`` and ``.globl``
2786) macro related directives, including ``.altmacro``, ``.macro``, and ``.endm``
2797) code bit related directives, including ``.code16``, ``.code32``, and ``.code64``
2808) section related directives, including ``.section``, ``.data``, and ``.text``
2819) number emission related directives, including ``.byte``, ``.word``,
282   ``.short``, ``.long``, and ``.quad``
28310) ``.org`` shall be used with restrictions. It shall only be used to
284    advance the location counter due to code bit changes, such as change from 32-bit
285    mode to 64-bit mode.
286
287
288
289Functions
290*********
291
292ASM-FN-01: Function shall have return statement
293===============================================
294
295Compliant example::
296
297    asm_func_showcase:
298            movl    $0x2, %eax
299            ret
300
301    asm_showcase:
302            movl    $0x1, %eax
303            call    asm_func_showcase
304
305.. rst-class:: non-compliant-code
306
307   Non-compliant example::
308
309       asm_func_showcase:
310               movl    $0x2, %eax
311
312       asm_showcase:
313               movl    $0x1, %eax
314               call    asm_func_showcase
315
316
317ASM-FN-02: A function shall have only one entry point
318=====================================================
319
320The label in a function shall be used only inside. Jumping into the function
321from outside via this label shall not be allowed. This rule applies to both
322conditional jumps and unconditional jumps.
323
324Compliant example::
325
326    asm_func_showcase:
327            test    $0x400, %eax
328            jne     tmp
329            movl    $0x1, %eax
330    tmp:
331            movl    $0x2, %eax
332            ret
333
334    asm_showcase:
335            movl    $0x1, %eax
336            call    asm_func_showcase
337
338.. rst-class:: non-compliant-code
339
340   Non-compliant example::
341
342       asm_func_showcase:
343               movl    $0x1, %eax
344       tmp:
345               movl    $0x2, %eax
346               ret
347
348       asm_showcase:
349               movl    $0x1, %eax
350               call    asm_func_showcase
351               jmp     tmp
352
353
354ASM-FN-03: A function shall have only one return statement
355==========================================================
356
357Compliant example::
358
359    asm_func_showcase:
360            test    $0x400, %eax
361            jne     tmp
362            movl    $0x2, %eax
363            jmp     showcase_return
364    tmp:
365            movl    $0x3, %eax
366    showcase_return:
367            ret
368
369.. rst-class:: non-compliant-code
370
371   Non-compliant example::
372
373       asm_func_showcase:
374               test    $0x400, %eax
375               jne     tmp
376               movl    $0x2, %eax
377               ret
378       tmp:
379               movl    $0x3, %eax
380               ret
381
382
383ASM-FN-04: Function shall be entered only by explicit call
384==========================================================
385
386Falling through from a prior instruction shall not be allowed.
387
388Compliant example::
389
390    asm_func_showcase:
391            movl    $0x2, %eax
392            ret
393
394    asm_showcase:
395            movl    $0x1, %eax
396            call    asm_func_showcase
397
398.. rst-class:: non-compliant-code
399
400   Non-compliant example::
401
402       asm_showcase:
403               movl    $0x1, %eax
404
405       asm_func_showcase:
406               movl    $0x2, %eax
407               ret
408
409
410ASM-FN-05: A jump instruction shall not be used to jump out of a function
411=========================================================================
412
413This rule applies to both conditional jumps and unconditional jumps.
414
415Compliant example::
416
417    asm_func_showcase:
418            movl    $0x2, %eax
419            ret
420
421    asm_showcase:
422            movl    $0x1, %eax
423            call    asm_func_showcase
424
425.. rst-class:: non-compliant-code
426
427   Non-compliant example::
428
429       asm_func_showcase:
430               movl    $0x2, %eax
431               jmp     asm_test
432               ret
433
434       asm_showcase:
435               movl    $0x1, %ebx
436               call    asm_func_showcase
437
438       asm_test:
439               cli
440
441
442ASM-FN-06: Recursion shall not be used in function calls
443========================================================
444
445Compliant example::
446
447    asm_func_showcase:
448            movl    $0x2, %eax
449            ret
450
451    asm_showcase:
452            movl    $0x1, %eax
453            call    asm_func_showcase
454
455.. rst-class:: non-compliant-code
456
457   Non-compliant example::
458
459       asm_func_showcase:
460               movl    $0x2, %eax
461               call    asm_func_showcase
462               ret
463
464       asm_showcase:
465               movl    $0x1, %eax
466               call    asm_func_showcase
467
468
469ASM-FN-07: Cyclomatic complexity shall be less than 10
470======================================================
471
472A function with cyclomatic complexity greater than 10 shall be split into
473multiple sub-functions to simplify the function logic.
474
475Compliant example::
476
477    asm_func_showcase:
478            /* do something */
479            cmpl    $0x0, %eax
480            je      tmp
481            cmpl    $0x1, %eax
482            je      tmp
483            cmpl    $0x2, %eax
484            je      tmp
485            /* do something */
486    tmp:
487            /* do something */
488            ret
489
490.. rst-class:: non-compliant-code
491
492   Non-compliant example::
493
494       asm_func_showcase:
495               /* do something */
496               cmpl    $0x0, %eax
497               je      tmp
498               cmpl    $0x1, %eax
499               je      tmp
500               cmpl    $0x2, %eax
501               je      tmp
502               cmpl    $0x3, %eax
503               je      tmp
504               cmpl    $0x4, %eax
505               je      tmp
506               cmpl    $0x5, %eax
507               je      tmp
508               cmpl    $0x6, %eax
509               je      tmp
510               cmpl    $0x7, %eax
511               je      tmp
512               cmpl    $0x8, %eax
513               je      tmp
514               cmpl    $0x9, %eax
515               je      tmp
516               cmpl    $0xa, %eax
517               je      tmp
518               cmpl    $0xb, %eax
519               je      tmp
520               cmpl    $0xc, %eax
521               je      tmp
522               cmpl    $0xd, %eax
523               je      tmp
524               cmpl    $0xe, %eax
525               je      tmp
526               /* do something */
527       tmp:
528               /* do something */
529               ret
530
531
532
533Coding Style
534************
535
536ASM-CS-01: One instruction statement shall not be split into multiple lines
537===========================================================================
538
539Compliant example::
540
541    movl    $0x2, %eax
542
543.. rst-class:: non-compliant-code
544
545   Non-compliant example::
546
547       movl    $0x2, \
548       %eax
549
550
551ASM-CS-02: Assembler directive statements shall be aligned
552==========================================================
553
554An assembler directive statement is composed of directive and arguments.
555Arguments are optional depending on the use case.
556Some detailed rules about the alignment are listed below:
557
558a) Assembler directives shall be aligned with one tab if the statement is in the
559   code block under any label from functional perspective. Otherwise, assembler
560   directives shall be aligned to the start of the line.
561b) Tabs shall be used to separate the directive and the first argument, where
562   applicable. The number of tabs could be decided by the developers based on each
563   case and it shall guarantee that the first argument is aligned in each directive
564   block.
565c) A single space shall be used to separate multiple arguments.
566
567Compliant example::
568
569    .extern         cpu_primary_save32
570    .extern         cpu_primary_save64
571
572    .section        multiboot_header, "a"
573    .align          4
574    .long           0x0008
575    .long           0x0018
576
577    .section        entry, "ax"
578    .align          8
579    .code32
580
581.. rst-class:: non-compliant-code
582
583   Non-compliant example::
584
585          .extern      cpu_primary_save32
586          .extern   cpu_primary_save64
587
588       .section     multiboot_header, "a"
589       .align  4
590       .long     0x0008
591       .long   0x0018
592
593          .section   entry, "ax"
594          .align   8
595         .code32
596
597
598ASM-CS-03: Labels shall be aligned to the start of the line
599===========================================================
600
601Compliant example::
602
603    asm_showcase_1:
604            movl    $0x1, %eax
605
606    asm_showcase_2:
607            movl    $0x2, %eax
608
609.. rst-class:: non-compliant-code
610
611   Non-compliant example::
612
613         asm_showcase_1:
614            movl    $0x1, %eax
615
616          asm_showcase_2:
617            movl    $0x2, %eax
618
619
620ASM-CS-04: Instruction statements shall be aligned
621==================================================
622
623An instruction statement is composed of instruction prefix, instruction
624mnemonic, and instruction operands. Instruction prefix and instruction operands
625are optional depending on the use case.
626Some detailed rules about the alignment are listed below:
627
628a) The start of instruction statements shall be aligned with one tab if the
629   instruction statement is in the code block under any label from functional
630   perspective. Otherwise, the start of instruction statements shall be aligned to
631   the start of the line. The start of the instruction could either be the
632   instruction mnemonic or the instruction prefix.
633b) One space shall be used to separate the instruction prefix and the
634   instruction mnemonic, where applicable.
635c) Tabs shall be used to separate the instruction mnemonic and the first
636   instruction operand, where applicable. The number of tabs could be decided by
637   the developers based on each case and it shall guarantee that the first
638   instruction operand in the code block under one label is aligned.
639d) A single space shall be used to separate multiple operands.
640
641Compliant example::
642
643    asm_showcase_1:
644            movl            $0x1, %eax
645            lock and        %rcx, (%rdx)
646
647    asm_showcase_2:
648            movl            $0x3, %eax
649
650.. rst-class:: non-compliant-code
651
652   Non-compliant example::
653
654       asm_showcase_1:
655       movl   $0x1, %eax
656         lock    and        %rcx, (%rdx)
657
658       asm_showcase_2:
659           movl     $0x2, %eax
660
661
662ASM-CS-05:  '//' shall not be used for comments
663===============================================
664
665'/* \*/' shall be used to replace '//' for comments.
666
667Compliant example::
668
669    /* This is a comment */
670    movl    $0x1, %eax
671
672.. rst-class:: non-compliant-code
673
674   Non-compliant example::
675
676       // This is a comment
677       movl    $0x1, %eax
678
679
680ASM-CS-06: Tabs shall be 8 characters wide
681==========================================
682
683A tab character shall be considered 8-character wide when limiting the line
684width.
685
686
687ASM-CS-07: Each line shall contain at most 120 characters
688=========================================================
689
690No more than 120 characters shall be on a line, with tab stops every 8
691characters.
692
693Compliant example::
694
695    /*
696     * This is a comment. This is a comment. This is a comment. This is a comment.
697     * This is a comment. This is a comment. This is a comment.
698     */
699
700.. rst-class:: non-compliant-code
701
702   Non-compliant example::
703
704       /* This is a comment. This is a comment. This is a comment. This is a comment. This is a comment. This is a comment. This is a comment. */
705
706
707ASM-CS-08: Legal entity shall be documented in every file
708=========================================================
709
710Legal entity shall be documented in a separate comments block at the start of
711every file.
712The following information shall be included:
713
714a) Copyright
715b) License (using an `SPDX-License-Identifier <https://spdx.org/licenses/>`_)
716
717Compliant example::
718
719    /* Legal entity shall be placed at the start of the file. */
720    -------------File Contents Start After This Line------------
721
722    /*
723     * Copyright (C) 2019-2022 Intel Corporation.
724     *
725     * SPDX-License-Identifier: BSD-3-Clause
726     */
727
728    /* Coding or implementation related comments start after the legal entity. */
729    .code64
730
731.. rst-class:: non-compliant-code
732
733   Non-compliant example::
734
735       /* Neither copyright nor license information is included in the file. */
736       -------------------File Contents Start After This Line------------------
737
738       /* Coding or implementation related comments start directly. */
739       .code64
740
741
742
743Naming Convention
744*****************
745
746ASM-NC-01: Lower case letters shall be used for case insensitive names
747======================================================================
748
749This rule applies to assembler directive, instruction prefix, instruction
750mnemonic, and register name.
751
752Compliant example::
753
754    .code64
755    lock and        %rcx, (%rdx)
756
757.. rst-class:: non-compliant-code
758
759   Non-compliant example::
760
761       .CODE64
762       LOCK AND        %RCX, (%RDX)
763
764
765ASM-NC-02: Names defined by developers shall use lower case letters
766===================================================================
767
768Names defined by developers shall use lower case letters with the following
769exception. If an object-like MACRO is defined with '#define', it shall be named
770with full upper case.
771
772Compliant example::
773
774    asm_showcase:
775            movl    $0x1, %eax
776
777.. rst-class:: non-compliant-code
778
779   Non-compliant example::
780
781       ASM_SHOWCASE:
782               movl    $0x1, %eax
783
784
785ASM-NC-03: Label name shall be unique
786=====================================
787
788Label name shall be unique with the following exception: Use of local labels
789is allowed. A local label is defined with the format ``N:``, where N
790represents any non-negative integer. Use ``Nb`` to refer to the most recent
791previous definition of that label. Use ``Nf`` to refer to the next definition
792of a local label.
793
794Compliant example::
795
796    asm_showcase_1:
797            movl    $0x1, %eax
798
799    asm_showcase_2:
800            movl    $0x2, %eax
801
802.. rst-class:: non-compliant-code
803
804   Non-compliant example::
805
806       asm_showcase:
807               movl    $0x1, %eax
808
809       asm_showcase:
810               movl    $0x2, %eax
811
812
813ASM-NC-04: Names defined by developers shall be fewer than 31 characters
814========================================================================
815
816Compliant example::
817
818    asm_showcase:
819            movl    $0x1, %eax
820
821.. rst-class:: non-compliant-code
822
823   Non-compliant example::
824
825       asm_showcase_asm_showcase_asm_showcase:
826               movl    $0x1, %eax
827
828
829
830ABI Conformance
831***************
832
833ASM-ABI-01: The implementation of Assembly code shall conform to the System V x86/AMD ABI
834=========================================================================================
835
836The implementation of Assembly code shall conform to the function calling
837sequence defined in System V Application Binary Interface AMD64 Architecture
838Processor Supplement.
839
840
841Refer to the `System V Application Binary Interface AMD64 Architecture Processor Supplement <https://www.intel.com/content/dam/develop/external/us/en/documents/mpx-linux64-abi.pdf>`_.
842