GCC-AVR Inline Assembler Cookbook Version 1.2

Transcription

1 GCC-AVR Inline Assemble Cookbook Vesion 1.2 About this Document The GNU C compile fo Atmel AVR isk pocessos offes, to embed assembly language code into C pogams. This cool featue may be used fo manually optimizing time citical pats of the softwae o to use specific pocesso instuction, which ae not available in the C language. Because of a lack of documentation, especially fo the AVR vesion of the compile, it may take some time to figue out the implementation details by studying the compile and assemble souce code. Thee ae also a few sample pogams available in the net. Hopefully this document will help to incease thei numbe. It's assumed, that you ae familia with witing AVR assemble pogams, because this is no AVR assemble pogamming tutoial. It's no C language tutoial eithe. Copyight (C) 2001 by egnite Softwae GmbH Pemission is ganted to copy and distibute vebatim copies of this manual povided that the copyight notice and this pemission notice ae peseved on all copies. Pemission is ganted to copy and distibute modified vesions of this manual povided that the entie esulting deived wok is distibuted unde the tems of a pemission notice identical to this one. This is an ealy elease of this document. It descibes vesion of the compile, but most pats ae still valid fo vesion Thee may be some pats, which hadn't been completely undestood by the autho himself and not all samples had been tested so fa. Because the autho is Geman and not familia with the English language, thee ae definitely some typos and syntax eos in the text. As a pogamme the autho knows, that a wong comment in the code sometimes might be wose than none. Anyway, he decided to offe his little knowledge to the public, in the hope to get enough esponse to impove this document. Feel fee to contact the autho via . Fo the latest elease check Hene, 7 th of May 2001 Haald Kipp haald.kipp@egnite.de Contents 1 GCC Statement asm Assemble Code Input and Output Opeands Clobbes Assemble Macos Index... 8 Histoy 07/05/01 V 1.1: Output and input lists sequence coected in chapte 1. Multibyte opeands added. Index added. Some typos coected. 07/05/01 V 1.2: subi eplaced by inc in clobbe samples. Pointe type is mandantoy. GCC-AVR Inline Assemble Cookbook 1/8

2 1 GCC Statement asm Let's stat with a simple example of eading a value fom pot D: asm("in %0, %1" : "=" (value) : "I" (PORTD) : Each asm statement is devided by colons into fou pats: 1. The assemble instuctions, defined as a single sting constant: "in %0, %1" 2. A list of output opeands, sepaated by commas. Ou example uses just one: "=" (value) 3. A comma sepaated list of input opeands. Again ou example uses one opeand only: "I" (PORTD) 4. Clobbeed egistes, left empty in ou example. You can wite assemble instuctions in much the same way like nomal assemble pogams. Howeve, egistes and constants ae used in a diffeent way, if they efe to expessions of you C pogam. The connection between egistes and C opeands is specified in the second and thid pat of the asm instuction, esp. the list of input and output opeands. The geneal fom is asm(code : output opeand list : input opeand list : clobbe list In the code section opeands ae efeed by a pecent sign followed by a single digit. %0 efes to the fist %1 to the second opeand and so foth. In example above %0 efes to "=" (value) and %1 efes to "P" (pot). This may still look a little odd now, but the syntax of an opeand list will be explained soon. Let us fist look to that pat of a compile listing, which may have been geneated fom ou example: lds 24,value /* #APP */ in 24, 12 /* #NOAPP */ sts value,24 The comments have been added by the compile to infom the assemble, that the included code has not been geneated by the compilation of C statements, but by inline assemble statements. The compile selected 24, to get the value. It may have selected any othe egiste, though. It may not explicitely load o stoe the value and it may even decide not to include you assemble code at all. All these decisions ae pat of the compile's optimization stategie. Fo example, if you neve use the vaiable value in the emaining pat of the C pogam, the compile will most likely emove you code, unless you switched off optimization. To avoid this, you can add the volatile attibute to the asm statement: asm volatile("in %0, %1" : "=" (value) : "I" (PORTD) : The last pat of the asm instuction, the clobbe list, is mainly used to tell the compile about modifications done by the assemble code. This pat may be omitted, all othe pats ae equied, but may be left empty. If you assemble outine won't use any input o output opeand, still two colons must follow the assemble code sting. A good example is a simple statement to disable inteupts: asm volatile("cli":: GCC-AVR Inline Assemble Cookbook 2/8

3 2 Assemble Code You can use the same assemble instuction mnemonics, as you'd use with any othe AVR assemble. And you can wite as many assemble statements into one code sting as you like and you flash memoy is able to hold. To make it moe eadable, you should put each statement on a sepeate line: asm volatile("nop\n\t" "nop\n\t" "nop\n\t" "nop\n\t" :: The linefeed and tab chaactes will make the assemble listing geneated by the compile moe eadable. It may look a bit odd fo the fist time, but that's the way the compile ceates it's own assemble code. You may also make use of some special egistes. Symbol SREG SP_H SP_L tmp_eg zeo_eg PC_ Registe Status egiste at addess 0x3F Stack pointe high byte at addess 0x3E Stack pointe low byte at addess 0x3D Registe 0, used fo tempoay stoage Registe 1, always zeo Pogam counte? Registe 0 may be feely used by you assemble code and need not to be estoed at the end of you code. It's a good idea to use tmp_eg and zeo_eg instead of 0 o 1, just in case a new compile vesion might change the egiste definitions. 3 Input and Output Opeands Each input and output opeand is descibed by a constaint sting followed by a C expession in paantheses. GCC-AVR knows the following constaint chaactes: Constaint Used fo Range a Simple uppe egistes 16 to 23 b Base pointe egistes pais y,z d Uppe egiste 16 to 31 e Pointe egiste pais x,y,z G Floating point constant 0.0 I 6-bit positive intege constant 0 to 63 J 6-bit negative intege constant -63 to 0 K Intege constant 2 (Pogam counte?) L Intege constant 0 l Lowe egistes 0 to 15 M 8-bit intege constant 0 to 255 N Intege constant -1 O Intege constant 8, 16, 24 P Intege constant 1 Any egiste 0 to 31 t Tempoay egiste 0 w Special uppe egiste pais 24, 26, 28, 30 x Pointe egiste pai X x (27:26) y Pointe egiste pai Y y (29:28) z Pointe egiste pai Z z (31:30) These definitions seem not to fit popely to the AVR instuction set. The autho's assumption is, that this pat of the compile has neve been eally finished in this vesion, but that assumption may be wong. The selection of the pope containt depends on the ange of the constants o egistes, which must be acceptable to the AVR instuction they ae used with. The C compile doesn't check any line of you assemble code. But it is able to check the constaint against you C expession. Howeve, if you specify the wong constaints, then the compile may silently pass wong code to the assemble. And, of couse, the assemble will fail with some cyptic output o intenal eos. Fo example, if you specify the constaint "" and you ae using this egiste with an "oi" instuction in you assemble code, then the compile may select any egiste. This will fail, if the compile GCC-AVR Inline Assemble Cookbook 3/8

4 chooses 2 to 15. (It will neve choose 0 o 1, because these ae uses fo special puposes.) That's why the coect constaint in that case is "d". On the othe hand, if you use the constaint "M", the compile will take cae, that you don't pass anything else but an 8-bit value. Late on we will see, how to pass multibyte expession esults to the assemble code. The following table shows all AVR assemble mnemonics, which equie opeands, and the elated containts. Because of the impope constaint definitions in vesion , they aen't stict enough. Thee is, fo example, no constaint, which esticts intege constants to the ange 0 to 7 fo bit set and bit clea opeations. Mnemo adc add adiw and andi as bcl bld bbc bbs bset bst cbi cb Constaints w,i I,I I,label I,label I,I I,I d,i com cp cpc cpi cpse dec elpm eo in inc ld ldd ldi lds lpm t,z,i,e,b,label t,z lsl ls mov mul neg o oi out pop push ol o sbc sbci sbi I, I,I sbic sbiw sb sbc sbs se st std sts sub subi swap I,I w,i,i,i d e, b, label, Constaint chaactes may be pepended by a single constaint modifie. Containts without a modifie specify ead-only opeands. Modifies ae: Modifie Specifies = Wite-only opeand + Read-wite opeand (not suppoted by inline assemble) & Registe should be used fo output only Output opeands must be wite-only and the C expession esult must be an lvalue, which means that they must be valid on the left side of assignments. Note, that the compile will not check, if they ae of easonable type fo the kind of opeation used in the assemble instuctions. Input opeands ae, you guessed it, ead-only. But what, if you need the same opeand fo input and output, as ead-wite opeands ae not suppoted? As stated above, ead-wite opeands ae not suppoted in inline assemble code. But thee's anothe solution. Fo input opeatos it is possible to use a single digit in the constaint sting. Using digit n tells the compile to use the same egiste as fo the n-th opeand, stating with zeo. Hee is an example: asm volatile("swap %0" : "=" (value) : "0" (value) This statement will swap the nibbles of an 8-bit vaiable named value. Constaint "0" tells the compile, to use the same input egiste as fo the fist opeand. Note howeve, that this doesn't automatically imply the evese case. The compile may choose the same egistes fo input and output, even if not told to do so. This is no poblem in most cases, but may be fatal, if the output opeato is modified by the assemble code befoe the input opeato is used. In situation, whee you code depends on diffeent egistes used fo input and output opeands, you must add the & constaint modifie to you output opeand. The following example demonstates this poblem: asm volatile("in %0,%1" "out %1, %2" : "=&" (input) : "I" (pot), "" (output) In this example an input value is ead fom a pot and then an output value is witten to the same pot. If the compile would have choosen the same egiste fo input and output, then the output value would have been GCC-AVR Inline Assemble Cookbook 4/8

5 destoyed on the fist assemble instuction. Fotunately this example uses the & constaint modifie to instuct the compile not to select any egiste fo the output value, which is used fo any of the input opeands. Back to swapping. Hee is the code to swap high and low byte of a 16-bit value: asm volatile("mov tmp_eg, %A0" "mov %A0, %B0" "mov %B0, tmp_eg " : "=" (value) : "0" (value) Fist you will notice the usage of egiste tmp_eg, which we listed among othe special egistes in chapte 2. You can use this egiste without saving its contents. Completely new ae those lettes A and B in %A0 and %B0. In fact they efe to two diffeent 8-bit egistes, both containing a pat of value. Anothe example to swap bytes of a 32-bit value: asm volatile("mov tmp_eg, %A0" "mov %A0, %D0" "mov %D0, tmp_eg " "mov tmp_eg, %B0" "mov %B0, %C0" "mov %C0, tmp_eg " : "=" (value) : "0" (value) Now the explanation of the additional lettes becomes tivial. If the opeand assigned to an 8-bit egiste is a multibyte opeand, then the compile will automatically assign enough egistes to hold the entie opeand. In the assemble code you use %A0 to efe to the lowest byte of the fist opeand, %A1 to the lowest byte of the second opeand and so on. The next byte of the fist opeand will be %B0, the next byte %C0 and so on. This also implies, that it might be sometimes neccessay to cast the type of an input opeand to the desied size. 4 Clobbes As stated peviously, the last pat of the asm statement, the list of clobbes, may be omitted, including the colon sepeato. Howeve, if you ae using egistes, which had not been passed as opeands, you need to infom the compile about this. The following example will do an atomic incement. It incements an 8-bit value pointed to by a pointe vaiable in one go, without being inteupted by an inteupt outine o anothe thead in a multitheaded envionment. Note, that we must use a pointe, because the incemented value needs to be stoed befoe inteupts ae enabled. asm volatile( "cli" "ld 24, %a0" "inc 24" "st %a0, 24" "sei" : : "z" (pt) : "24" GCC-AVR Inline Assemble Cookbook 5/8

6 The compile might poduce the following code: cli ld 24, Z inc 24 st Z, 24 sei One easy solution to avoid clobbeing egiste 24 is, to make use of the special tempoay egiste tmp_eg defined by the compile. asm volatile( "cli" "ld tmp_eg, %a0" "inc tmp_eg " "st %a0, tmp_eg " "sei" : : "z" (pt) The compile is pepaed to eload this egiste next time it uses it. Anothe poblem with the above code is, that it should not be called in code sections, whee inteupts ae disabled and should be kept disabled, because it will enable inteupts at the end. We may stoe the cuent status, but then we need anothe egiste. Again we can solve this without clobbeing a fixed, but let the compile select it. This could be done with the help of a local C vaiable. { } uint8_t s; asm volatile( "in %0, SREG " "cli" "ld tmp_eg, %a1" "inc tmp_eg " "st %a1, tmp_eg " "out SREG, %0" : "=&" (t) : "z" (pt) Now anything seems coect, but it isn't eally. The assemble code modifies the vaiable, that pt points to. The compile will not ecognize this and may keep its value in any of the othe egistes. Not only, that the compile woks with the wong value, but also the assemble code does, because the C pogam may have modified the value too, but the compile didn't update the memoy location fo optimization easons. The wost thing you can do in this case: { } uint8_t s; asm volatile( "in %0, SREG " "cli" "ld tmp_eg, %a1" "inc tmp_eg " "st %a1, tmp_eg " "out SREG, %0" : "=&" (t) : "z" (pt) : "memoy" GCC-AVR Inline Assemble Cookbook 6/8

7 The special clobbe "memoy" infoms the compile, that the assemble code may modify any memoy location. It foces the compile to update all vaiables, which contents is cuently hold in a egiste befoe executing the assemble code. And of couse, eveything has to be eloaded again afte this code. In most situations a much bette solution would be to declae the pointe destination itself volatile: volatile uint8_t *pt; This way, the compile expects the value pointed to by pt to be changed and will load it wheneve used and stoe it wheneve modified. Situation, in which you need clobbes, ae vey ae. In most cases thee will be bette ways. Clobbeed egistes will foce the compile to stoe thei values befoe and eload them afte you assemble code. Avoiding them, enables the full optimization powe. 5 Assemble Macos In ode to euse you assemble language pats, it is useful to define them as macos and put them into include files. GCC-AVR comes with a bunch of them, which could be found in the diectoy av/include. Using such include files may poduce compile wanings, if they ae used in modules, which ae compiled in stict ANSI mode. To avoid that, you can wite asm instead of asm and volatile instead of volatile. These ae equivalent aliases. Anothe poblem with eused macos aises, if you ae using labels. In such cases you may make use of the special patten %=, which is eplaced by a unique numbe on each asm statement. The following code had been taken fom av/include/iomacos.h: #define loop_until_bit_is_clea(pot, bit) \ asm volatile ( \ "L_%=: " "sbic %0, %1" \ "jmp L_%=" \ : /* no outputs */ \ : "I" ((uint8_t)(pot)), \ "I" ((uint8_t)(bit)) \ ) When used fo the fist time, L_%= may be tanslated to L_1404, the next usage might ceate L_1405 o whateve. In any case, the labels became unique too. GCC-AVR Inline Assemble Cookbook 7/8

8 6 Index %= 7 %0 2 %A0 5 asm 7 SP_H 3 SP_L 3 SREG 3 tmp_eg 3, 6 volatile 7 zeo_eg 3 16-bit value 5 32-bit value 5 8-bit value 4 asm 2 assemble code 3 assemble mnemonics 4 atomic incement 5 clobbes 5 constaint chaactes 3 constaint modifie 4 intenal eo 3 inteupt 2, 6 labels 7 local vaiable 6 lvalue 4 macos 7 memoy 7 multibyte opeand 5 opeands 3 optimization 2, 6 stack pointe 3 status egiste 3 type cast 5 unique numbe 7 volatile 2, 7 GCC-AVR Inline Assemble Cookbook 8/8