[編程技巧]Freescale 匯編語言源程序標準
程序匠人 發表于 2005-9-29 13:14:00       閱讀全文(264) | 回復(0) | 引用(0) 
Freescale 匯編語言源程序標準
------------------------------------------------------
此標準包括:
  行的長度限制
  可接受的字符和字符格式
  源程序列的分配
  注釋格式
-------------------------------------------------------
行的長度:
   為了便于閱讀和打印,Freescale使用mono-spaced字體,這種字體每個字符寬度相等.字體大小是9 point;最大行長為70個字符.
示例如下:
;        1         2         3         4         5         6         7
;234567890123456789012345678901234567890123456789012345678901234567890
asc2hex:    bsr   ishex       ;check for valid hex # first
            bne   dunA2asc    ;if not just return
            cmp   #'9'        ;check for A-F ($41-$46)
            bls   notA2F      ;skip if not A-F
列表輸出文件示例如下:
;        1         2         3         4         5         6         7         8         9
;23456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123
  551 C1D7 AD EA     asc2hex:    bsr   ishex       ;check for valid hex # first
  552 C1D9 26 0A                 bne   dunA2asc    ;if not just return
  553 C1DB A1 39                 cmp   #'9'        ;check for A-F ($41-$46)
  554 C1DD 23 02                 bls   notA2F      ;skip if not A-F
從以上可以看出列寬最大到93字符,因為列表輸出文件并不能給讀者提供更多的有用信息,因此Freescale最大用到每行93字符.
-----------------------------------------------------------
避免使用TAB字符
    TAB字符在不同的字處理軟件中有不同的含義,當把源文件提交給其它文檔時可能會出現問題,所以要避免使用TAB,而用多個空格代替.
-----------------------------------------------------------
源程序列分配
   源程序由標號,助記符,操作數和注釋組成一行;
   標號在第1列開始
   指令助記符在第13列開始
   操作數在19列開始
   注釋在31列開始;如果操作數超過了30列,注釋必須和操作數的最后一個字符分開1到2個空格.
   如果一個標號超過11個字符,就應該另起一行,并在31列做注釋.短標號也可以另起一行來突出它,這經常用在一個子程序開始處.見圖3
;        1         2         3         4         5         6         7
;234567890123456789012345678901234567890123456789012345678901234567890
label:      mne   operand     ;comment
            brset very,long,operand   ;comment can’t start in col 31
veryLongLabel:                ;long label on separate line
            nop               ;instruction with no operands
short:                        ;short label may use a separate line
            mne operand       ;code to which ‘short’ refers
-----------------------------------------------------------
大寫和小寫字符
   源程序中協調一致的大小寫可以增強可讀性,并使程序變得容易理解.
   標號
   標號可以混和使用大小寫,但無論在哪兒引用它都應該嚴格匹配其初始定義.
   指令助記符
   指令助記符,匯編指示和預處理應當使用小寫字符.盡管他們可以使用大寫字符,但是輸入時要敲shift鍵,而且大寫字符使讀者變得不能專心閱讀.
   各種各樣得文檔中指令使用大寫字符僅僅是為了突出他們.有經驗得程序員使用小寫字符不但容易輸入而且容易閱讀.
寄存器和位
Freescale的頭文件中使用大寫字符定義寄存器和位.位的定義有兩種方法位號(0-7)和位屏蔽碼.位操作指令使用位號;邏輯操作指令使用屏蔽碼方式.屏蔽碼在位號前面加一個小寫字母m前綴.示例見圖4
PTAD:       equ   $00         ;I/O port A data register
; bit numbers for use in BCLR, BSET, BRCLR, and BRSET
PTAD7:      equ   7           ;bit #7
PTAD6:      equ   6           ;bit #6
PTAD5:      equ   5           ;bit #5
PTAD4:      equ   4           ;bit #4
PTAD3:      equ   3           ;bit #3
PTAD2:      equ   2           ;bit #2
PTAD1:      equ   1           ;bit #1
PTAD0:      equ   0           ;bit #0
; bit position masks
mPTAD7:     equ   %10000000   ;port A bit 7
mPTAD6:     equ   %01000000   ;port A bit 6
mPTAD5:     equ   %00100000   ;port A bit 5
mPTAD4:     equ   %00010000   ;port A bit 4
mPTAD3:     equ   %00001000   ;port A bit 3
mPTAD2:     equ   %00000100   ;port A bit 2
mPTAD1:     equ   %00000010   ;port A bit 1
mPTAD0:     equ   %00000001   ;port A bit 0
-----------------------------------------------------------
標號
   標號可以混和使用大小寫,但避免使用下劃線,我們推薦使用大寫字符做為多字符標號的分界.例如:VeryLongLabel代替ery_long_label
   標號定義并加一個冒號,盡管有很多編譯器不需要這個冒號.

文件和子程序頭
    文件和子程序前面需要一個塊來說明他的用途和目的,稱為頭
    圖5是典型的文件頭
;********************************************************************************************
;* Title: 9S08GB60_v1r2.equ                      (c) FREESCALE Inc. 2003 All rights reserved.
;********************************************************************************************
;* Author: Jim Sibigtroth - Freescale TSPG
;*
;* Description: Register and bit name definitions for 9S08GB60
;*
;* Documentation: 9S08GB60 family Data Sheet for register and bit explanations
;* HCS08 Family Reference Manual (HCS08RM1/D) appendix B for explanation of equate files
;*
;* Include Files: none
;*
;* Assembler: Metrowerks Code Warrior 3.0 (pre-release)
;*            or P&E Microcomputer Systems - CASMS08 (beta v4.02)
;*
;* Revision History:
;* Rev #  Date      Who     Comments
;* ----- ----------- ------ --------------------------------------------
;* 1.2   24-Apr-03   J-Sib  correct minor typos in comments
;* 1.1   21-Apr-03   J-Sib  comments and modify for CW 3.0 project
;* 1.0   15-Apr-03   J-Sib  Release version for 9S09GB60
;********************************************************************************************

    其中有些是必須的,有些可以省略
    文件名:必須,包括文件名和后綴
    版權聲明:必須
    作者:必須,有些文件可能重復使用數年,有時需要幫助時可以聯系他們
    描述:必須,但僅是摘要,更多信息應該在一個單獨的文件中
    文檔:另外一個文件,她是對這個文件的詳細說明
    包含文件:需要時必須
    匯編器:匯編器的廠商和版本,非常重要
    版本歷史:提供何時,何人,哪個文件被修改等信息

    圖6是子程序頭模板,可以根據子程序的復雜程度適當增減
;******************************************************************
;* RoutineName - expanded name or phrase describing purpose
;* Brief description, typically a few lines explaining the
;* purpose of the program.
;*
;* I/O: Explain what is expected and what is produced
;*
;* Calling Convention: How is the routine called?
;*
;* Stack Usage: (when needed) When a routine has several variables
;* on the stack, this section describes the structure of the
;* information.
;*
;* Information about routines that are called and any registers
;* that get destroyed. In general, if some registers are pushed at
;* the beginning and pulled at the end, it is not necessary to
;* describe this in the routine header.
;******************************************************************


;******************************************************************
;* GetSRec - retrieve one S-record via SCI1
;*  Terminal program should delay after <cr> to allow programming
;*  recommended delay after <cr> is TBDms, no delay after chars.
;*  Only header (S0), data (S1), and end (S9) records accepted
;*
;* Calling Convention:
;*             ais    #-bufferLength ;# of data bytes + 4 (typ.36)
;*             jsr    GetSRec       ;read S-record onto stack
;*             bne    error         ;Z=0 means record bad
;*;
;*; 'bufferLength' is defined in calling program not in this
;*; subroutine, calling routine must also deallocate buffer space
;*; after processing the information that was returned on the stack
;*;
;*             ais #bufferLength ;deallocate buffer space
;*
;* Returns: all but CCR Z-bit returned on stack (see stack map)
;*   CCR Z-bit = 1 if valid S-record; CCR Z-bit = 0 if not valid
;*   S-record type @ sp+1 (1 ASCII byte) ($30, $31, or $39)
;*   S-record size @ sp+2 (1 hex byte) (# of data bytes 0-31)
;*   S-record addr @ sp+3 (2 hex bytes) (addr of 1st data value)
;*   S-record data @ sp+5..sp+36 (up to 32 hex data bytes)
;*
;*  Stack map... S-record, return, and locals on stack
;*        |                 | <-sp (after local space allocated)
;*  H:X-> | SRecCount       |
;*        | SRecChkSum      | <-sp (after jsr)
;*        | ReturnAddr msb  |
;*        | ReturnAddr lsb  | <-sp (after rts)
;*        | SRecTyp         |
;*        | SRecSize        |
;*  H:X-> | SRecAddr msb    |
;*        | SRecAddr lsb    |
;*        | SRecData 00     |
;*        | SRecData 01     | etc... (up to 32 bytes)
;*
;*    Data values are read as two ASCII characters, converted to
;*    hex digits, combined into 1 hex value, and stored on stack
;*
;*  Calls: GetChar, PutChar, and GetHexByte
;*  Changes: A, H, and X
;******************************************************************
        圖7是一個復雜的頭,它使用堆棧傳遞參數并且附加的堆棧來分配局部變量.雖然可以描述很多的細節但我們規定頭的描述最好限制在3到4行.如果要求更多的細節,可以使用一個的單獨的文件,而不是描述在代碼文件中.
    調用協議是想當復雜的,因為用戶必須分配傳遞參數的堆棧空間,堆棧內的參數包括用戶填充的和本子程序返回的.當這個子程序放回后,一條BNE指令用來檢查Z標志來檢查本子程序是否成功得到一個S記錄.當檢查到一個錯誤或可處理的返回數據,調用程序必須處理調用前分配的傳遞參數的堆棧空間.
    堆棧的用法也非常復雜,因為本子程序在堆棧上處理信息,所以給讀者提供一個堆棧信息映像來幫助讀者理解這個子程序是非常重要的.這個映像展示了一個最大的塊,這個塊是在調用子程序之前分配的.返回地址做為JSR指令的結果也存儲在堆棧上.本子程序內部分配使用的2字節局部變量必須在返回調用程序之前處理完畢.
    在這個子程序的頭的最后
    調用項:列出本子程序需要調用的子程序.
    改變項:列出執行本子程序改變的寄存器
;******************************************************************
;* GetChar - wait indefinitely for a character to be received
;*  through SCI1 (until RDRF becomes set) then read char into A
;*  and return. Reading character clears RDRF. No error checking.
;*
;* Calling convention:
;*         jsr GetChar
;*
;* Returns: received character in A
;******************************************************************
   圖8展示一個簡單的子程序頭,這個頭不包含堆棧信息,也不調用其它子程序,所以這些信息都不需要了.
----------------------------------------------------------------
注釋:
    注釋是非常重要的,大多數注釋格式是以分號并從31列開始直到行尾.避免注釋重復說明指令內容.
    例如:lda pta          ;讀A口數據.
    取而代之注釋應傳遞這樣一些信息:為什么指令在這兒,指令如何描述程序功能或系統包含的嵌入式微控制器.
    這是一個好的注釋:
         lda PTAD            ;check for low on bit 7 (step switch)
    如果注釋過長不能在一行完成,那么應該在第1列單獨起一行,但不宜頻繁使用以防淹沒代碼行.如果是多行注釋可以寫成注釋塊,注釋塊與代碼行以空注釋行相分隔如下所示:
;
; In-line comment block. On rare occasions, an extended comment
; is needed to explain some important aspect of a program. Each
; line of the extended comment starts with a semicolon. A line
; with nothing but a semicolon in column 1 is used above and
; below the block comment to set it apart from code.
;

注釋格式基礎理論
    注釋或空行可以使程序組成邏輯段以提高可讀性.子程序頭塊可以標識一個子程序的開始.類似的分隔也是非常有用的.