Ignore:
Timestamp:
Apr 1, 2008, 5:07:25 PM (12 years ago)
Author:
mikel
Message:

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/modifying.xml

    r8820 r8981  
    8888Continue/Debugger/eXit <enter>?
    8989</programlisting>
     90
    9091      <para>As you may have noticed, it's not a perfect world; it's rare
    91 that the cause (attempting to reference the CDR of -1, and therefore
    92 accessing unmapped memory near location 0) of this effect (an
    93 "Unhandled exception ..." message) is so obvious.</para>
     92        that the cause (attempting to reference the CDR of -1, and therefore
     93        accessing unmapped memory near location 0) of this effect (an
     94        "Unhandled exception ..." message) is so obvious.</para>
    9495      <para>The addresses printed in the message above aren't very useful
    95 unless you're debugging the kernel with GDB (and they're often
    96 very useful if you are.)</para>
     96        unless you're debugging the kernel with GDB (and they're often
     97        very useful if you are.)</para>
    9798      <para>Aside from causing an exception that the lisp kernel doesn't
    98 know how to handle, one can also enter the kernel debugger (more)
    99 deliberately:</para>
     99        know how to handle, one can also enter the kernel debugger (more)
     100        deliberately:</para>
     101
    100102      <programlisting>
    101103? (defun classify (n)
     
    113115[12345] &CCL; kernel debugger:
    114116      </programlisting>
     117
    115118      <para>CCL::BUG isn't quite the right tool for this example (a
    116       call to BREAK or PRINT might do a better job of clearing up the
    117       mystery), but it's sometimes helpful when those other tools
    118       can't be used.  The lisp error system notices, for instance, if
    119       attempts to signal errors themselves cause errors to be
    120       signaled; this sort of thing can happen if CLOS or the I/O
    121       system are broken or missing. After some small number of
    122       recursive errors, the error system gives up and calls
    123       CCL::BUG.</para>
     119        call to BREAK or PRINT might do a better job of clearing up the
     120        mystery), but it's sometimes helpful when those other tools
     121        can't be used.  The lisp error system notices, for instance, if
     122        attempts to signal errors themselves cause errors to be
     123        signaled; this sort of thing can happen if CLOS or the I/O
     124        system are broken or missing. After some small number of
     125        recursive errors, the error system gives up and calls
     126        CCL::BUG.</para>
    124127      <para>If one enters a '?' at the kernel debugger prompt, one
    125       will see output like:</para>
     128        will see output like:</para>
     129
    126130      <programlisting>
    127131(S)  Find and describe symbol matching specified name
     
    130134(K)  Kill &CCL; process
    131135(?)  Show this help
    132 </programlisting>
     136      </programlisting>
     137
    133138      <para>CCL::BUG just does an FF-CALL into the lisp kernel.  If
    134       the kernel debugger was invoked because of an unhandled
    135       exception (such as an illegal memory reference) the OS kernel
    136       saves the machine state ("context") in a data structure for us,
    137       and in that case some additional options can be used to display
    138       the contents of the registers at the point of the
    139       exception. Another function - CCL::DBG - causes a special
    140       exception to be generated and enters the lisp kernel debugger
    141       with a non-null "context":</para>
     139        the kernel debugger was invoked because of an unhandled
     140        exception (such as an illegal memory reference) the OS kernel
     141        saves the machine state ("context") in a data structure for us,
     142        and in that case some additional options can be used to display
     143        the contents of the registers at the point of the
     144        exception. Another function - CCL::DBG - causes a special
     145        exception to be generated and enters the lisp kernel debugger
     146        with a non-null "context":</para>
     147
    142148      <programlisting>
    143149? (defun classify2 (n)
     
    165171(?)  Show this help
    166172</programlisting>
     173
    167174      <para>CCL::DBG takes an argument, whose value is copied into the register
    168 that &CCL; uses to return a function's primary value (arg_z, which
    169 is r23 on the PowerPC). If we were to choose the (L) option at this point,
    170 we'd see a dislay like:</para>
    171       <programlisting>rnil = 0x01836015
     175        that &CCL; uses to return a function's primary value (arg_z, which
     176        is r23 on the PowerPC). If we were to choose the (L) option at this point,
     177        we'd see a dislay like:</para>
     178
     179      <programlisting>
     180rnil = 0x01836015
    172181nargs = 0
    173182r16 (fn) = #&lt;Function CLASSIFY2 #x30379386>
     
    187196r25 (save6) = ()
    188197r24 (save7) = ()
    189 </programlisting>
     198      </programlisting>
     199
    190200      <para>From this we can conclude that the problematic argument to CLASSIFY2
    191 was 0 (see r23/arg_z), and that I need to work on a better example.</para>
     201        was 0 (see r23/arg_z), and that I need to work on a better example.</para>
    192202      <para>The R option shows the values of the ALU (and PPC branch unit)
    193 registers in hex; the F option shows the values of the FPU registers.</para>
     203        registers in hex; the F option shows the values of the FPU registers.</para>
    194204      <para>The (B) option shows a raw stack backtrace; it'll try to
    195 identify foreign functions as well as lisp functions. (Foreign function
    196 names are guesses based on the nearest preceding exported symbol.)</para>
     205        identify foreign functions as well as lisp functions. (Foreign function
     206        names are guesses based on the nearest preceding exported symbol.)</para>
    197207      <para>If you ever unexpectedly find yourself in the "lisp kernel
    198 debugger", the output of the (L) and (B) options are often the most
    199 helpful things to include in a bug report.</para>
     208        debugger", the output of the (L) and (B) options are often the most
     209        helpful things to include in a bug report.</para>
    200210    </sect1>
    201211
     
    205215      <sect2 id="Overview--16-">
    206216        <title>Overview</title>
    207         <para>It's now possible to use AltiVec instructions in PPC LAP
    208         (assembler) functions.</para>
    209         <para>The lisp kernel detects the presence or absence of
    210         AltiVec and preserves AltiVec state on lisp thread switch and
    211         in response to exceptions, but the implementation doesn't
    212         otherwise use vector operations.</para>
    213         <para>This document doesn't document PPC LAP programming in
    214         general.  Ideally, there would be some document that
    215         did.</para>
    216         <para>This document does explain AltiVec register-usage
    217         conventions in &CCL; and explains the use of some lap macros
    218         that help to enforce those conventions.</para>
    219         <para>All of the global symbols described below are exported
    220         from the CCL package. Note that lap macro names, ppc
    221         instruction names, and (in most cases) register names are
    222         treated as strings, so this only applies to functions and
    223         global variable names.</para>
    224         <para>Much of the &CCL; support for AltiVec LAP programming
    225         is based on work contributed to MCL by Shannon Spires.</para>
     217    <para>It's now possible to use AltiVec instructions in PPC LAP
     218      (assembler) functions.</para>
     219    <para>The lisp kernel detects the presence or absence of
     220      AltiVec and preserves AltiVec state on lisp thread switch and
     221      in response to exceptions, but the implementation doesn't
     222      otherwise use vector operations.</para>
     223    <para>This document doesn't document PPC LAP programming in
     224      general.  Ideally, there would be some document that
     225      did.</para>
     226    <para>This document does explain AltiVec register-usage
     227      conventions in &CCL; and explains the use of some lap macros
     228      that help to enforce those conventions.</para>
     229    <para>All of the global symbols described below are exported
     230      from the CCL package. Note that lap macro names, ppc
     231      instruction names, and (in most cases) register names are
     232      treated as strings, so this only applies to functions and
     233      global variable names.</para>
     234    <para>Much of the &CCL; support for AltiVec LAP programming
     235      is based on work contributed to MCL by Shannon Spires.</para>
    226236      </sect2>
    227237
    228238      <sect2 id="Register-usage-conventions">
    229239        <title>Register usage conventions</title>
    230         <para>&CCL; LAP functions that use AltiVec instructions must
    231         interoperate with each other and with C functions; that
    232         suggests that they follow C AltiVec register usage
    233         conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
    234         value, vr14-vr19 temporaries, vr20-vr31 callee-save
    235         non-volatile registers.)</para>
    236         <para>The EABI (Embedded Application Binary Interface) used in
    237         LinuxPPC doesn't ascribe particular significance to the vrsave
    238         special-purpose register; on other platforms (notably MacOS),
    239         it's used as a bitmap which indicates to system-level code
    240         which vector registers contain meaningful values.</para>
    241         <para>The WITH-ALTIVEC-REGISTERS lapmacro generates code which
    242         which saves, updates, and restores VRSAVE on platforms where
    243         this is required (as indicated by the value of the special
    244         variable which controls this) and ignores VRSAVE on platforms
    245         that don't require it to be maintained.</para>
    246         <para>On all PPC platforms, it's necessary to save any non-volatile
    247 vector registers (vr20 .. vr31) before assigning to them and to restore
    248 such registers before returning to the caller.</para>
    249         <para>On platforms that require that VRSAVE be maintained, it's not
    250 necessary to mention the "use" of vector registers that're
    251 used as incoming parameters. It's not incorrect to mention their use
    252 in a WITH-ALTIVEC-REGISTERS form, but it may be unneccessary in many
    253 interesting cases. One can likewise assume that the caller of any function
    254 that returns a vector value (in vr2 has already set the apropriate bit in
    255 VRSAVE to indicate that this register is live. One could therefore write a
    256 leaf function that added the bytes in vr3 and vr2 and returned the result
    257 in vr2 as:</para>
     240    <para>&CCL; LAP functions that use AltiVec instructions must
     241      interoperate with each other and with C functions; that
     242      suggests that they follow C AltiVec register usage
     243      conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
     244      value, vr14-vr19 temporaries, vr20-vr31 callee-save
     245      non-volatile registers.)</para>
     246    <para>The EABI (Embedded Application Binary Interface) used in
     247      LinuxPPC doesn't ascribe particular significance to the vrsave
     248      special-purpose register; on other platforms (notably MacOS),
     249      it's used as a bitmap which indicates to system-level code
     250      which vector registers contain meaningful values.</para>
     251    <para>The WITH-ALTIVEC-REGISTERS lapmacro generates code which
     252      which saves, updates, and restores VRSAVE on platforms where
     253      this is required (as indicated by the value of the special
     254      variable which controls this) and ignores VRSAVE on platforms
     255      that don't require it to be maintained.</para>
     256    <para>On all PPC platforms, it's necessary to save any non-volatile
     257      vector registers (vr20 .. vr31) before assigning to them and to restore
     258      such registers before returning to the caller.</para>
     259    <para>On platforms that require that VRSAVE be maintained, it's not
     260      necessary to mention the "use" of vector registers that are
     261      used as incoming parameters. It's not incorrect to mention their use
     262      in a WITH-ALTIVEC-REGISTERS form, but it may be unnecessary in many
     263      interesting cases. One can likewise assume that the caller of any function
     264      that returns a vector value (in vr2 has already set the appropriate bit in
     265      VRSAVE to indicate that this register is live. One could therefore write a
     266      leaf function that added the bytes in vr3 and vr2 and returned the result
     267      in vr2 as:</para>
     268
    258269        <programlisting>
    259270(defppclapfunction vaddubs ((y vr3) (z vr2))
     
    261272  (blr))
    262273</programlisting>
     274
    263275        <para>When vector registers that aren't incoming parameters are used
    264 in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
    265 and of saving/restoring any non-volatile vector registers:</para>
     276          in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
     277          and of saving/restoring any non-volatile vector registers:</para>
     278
    266279        <programlisting>
    267280(defppclapfunction load-array ((n arg_z))
     
    276289    (dbg t)) ; Look at result in some debugger
    277290  (blr))
    278 </programlisting>
     291        </programlisting>
     292
    279293        <para>AltiVec registers are not preserved by CATCH and UNWIND-PROTECT.
    280 Since AltiVec is only accessible from LAP in &CCL; and since LAP
    281 functions rarely use high- level control structures, this should rarely be
    282 a problem in practice.</para>
     294          Since AltiVec is only accessible from LAP in &CCL; and since LAP
     295          functions rarely use high- level control structures, this should rarely be
     296          a problem in practice.</para>
    283297        <para>LAP functions which use non-volatile vector registers and which call
    284 (Lisp ?) code which may use CATCH or UNWIND-PROTECT should save those
    285 vector registers before such a call and restore them on return. This is
    286 one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
     298          (Lisp ?) code which may use CATCH or UNWIND-PROTECT should save those
     299          vector registers before such a call and restore them on return. This is
     300          one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
    287301      </sect2>
    288302    </sect1>
     
    292306
    293307      <refentry id="v_warn-if-redefine-kernel">
    294         <indexterm zone="v_warn-if-redefine-kernel">
    295           <primary>*warn-if-redefine-kernel</primary>
    296         </indexterm>
    297 
    298         <refnamediv>
    299           <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
    300           <refpurpose></refpurpose>
    301           <refclass>Variable</refclass>
    302         </refnamediv>
    303 
    304         <refsect1>
    305           <title>Description</title>
    306 
    307           <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
    308           functions and methods that are marked as being
    309           &#34;predefined&#34; signal continuable errors.</para>
    310 
    311           <para>Note that these are CERRORs, not warnings, and that
    312           no lisp functions or methods have been defined in the kernel
    313           in MCL or &CCL; since 1987 or so.</para>
    314         </refsect1>
     308            <indexterm zone="v_warn-if-redefine-kernel">
     309              <primary>*warn-if-redefine-kernel</primary>
     310            </indexterm>
     311
     312            <refnamediv>
     313              <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
     314              <refpurpose></refpurpose>
     315              <refclass>Variable</refclass>
     316            </refnamediv>
     317
     318            <refsect1>
     319              <title>Description</title>
     320
     321              <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
     322                functions and methods that are marked as being
     323                &#34;predefined&#34; signal continuable errors.</para>
     324
     325              <para>Note that these are CERRORs, not warnings, and that
     326                no lisp functions or methods have been defined in the kernel
     327                in MCL or &CCL; since 1987 or so.</para>
     328            </refsect1>
    315329      </refentry>
    316330
    317331      <refentry id="f_set-development-environment">
    318         <indexterm zone="f_set-development-environment">
    319           <primary>set-development-environment</primary>
    320         </indexterm>
    321 
    322         <refnamediv>
    323           <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
    324           <refpurpose></refpurpose>
    325           <refclass>Function</refclass>
    326         </refnamediv>
    327 
    328         <refsynopsisdiv>
    329           <synopsis><function>set-development-environment</function>
    330           &optional;
    331           unmark-builtin-functions</synopsis>
    332         </refsynopsisdiv>
    333 
    334         <refsect1>
    335           <title>Description</title>
    336 
    337           <para>Arranges that the outermost special bindings of *PACKAGE*
    338           and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
    339           package and NIL to these variables, respectively. If the optional
    340           argument is true, marks all globally defined functions and methods
    341           as being &#34;not predefined&#34; (this is a fairly expensive
    342           operation.)</para>
    343         </refsect1>
     332            <indexterm zone="f_set-development-environment">
     333              <primary>set-development-environment</primary>
     334            </indexterm>
     335
     336            <refnamediv>
     337              <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
     338              <refpurpose></refpurpose>
     339              <refclass>Function</refclass>
     340            </refnamediv>
     341
     342            <refsynopsisdiv>
     343              <synopsis><function>set-development-environment</function>
     344                &optional;
     345                unmark-builtin-functions</synopsis>
     346            </refsynopsisdiv>
     347
     348            <refsect1>
     349              <title>Description</title>
     350
     351              <para>Arranges that the outermost special bindings of *PACKAGE*
     352                and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
     353                package and NIL to these variables, respectively. If the optional
     354                argument is true, marks all globally defined functions and methods
     355                as being &#34;not predefined&#34; (this is a fairly expensive
     356                operation.)</para>
     357            </refsect1>
    344358      </refentry>
    345359
    346360      <refentry id="f_set-user-environment">
    347         <indexterm zone="f_set-user-environment">
    348           <primary>set-user-environment</primary>
    349         </indexterm>
    350 
    351         <refnamediv>
    352           <refname>SET-USER-ENVIRONMENT</refname>
    353           <refpurpose></refpurpose>
    354           <refclass>Function</refclass>
    355         </refnamediv>
    356 
    357         <refsynopsisdiv>
    358           <synopsis><function>set-user-environment</function>
    359           &optional; mark-builtin-functions</synopsis>
    360         </refsynopsisdiv>
    361 
    362         <refsect1>
    363           <title>Description</title>
    364 
    365           <para>Arranges that the outermost special bindings of *PACKAGE*
    366           and *WARN-IF-REDEFINE-KERNEL* restore values of the
    367           &#34;CL-USER&#34; package and T to these variables, respectively.
    368           If the optional argument is true, marks all globally defined
    369           functions and methods as being &#34;predefined&#34; (this is a
    370           fairly expensive operation.)</para>
    371         </refsect1>
     361            <indexterm zone="f_set-user-environment">
     362              <primary>set-user-environment</primary>
     363            </indexterm>
     364
     365            <refnamediv>
     366              <refname>SET-USER-ENVIRONMENT</refname>
     367              <refpurpose></refpurpose>
     368              <refclass>Function</refclass>
     369            </refnamediv>
     370
     371            <refsynopsisdiv>
     372              <synopsis><function>set-user-environment</function>
     373                &optional; mark-builtin-functions</synopsis>
     374            </refsynopsisdiv>
     375
     376            <refsect1>
     377              <title>Description</title>
     378
     379              <para>Arranges that the outermost special bindings of *PACKAGE*
     380                and *WARN-IF-REDEFINE-KERNEL* restore values of the
     381                &#34;CL-USER&#34; package and T to these variables, respectively.
     382                If the optional argument is true, marks all globally defined
     383                functions and methods as being &#34;predefined&#34; (this is a
     384                fairly expensive operation.)</para>
     385            </refsect1>
    372386      </refentry>
    373387      <refentry id="v_altivec-available">
    374         <indexterm zone="v_altivec-available">
    375           <primary>*altivec-available*</primary>
    376         </indexterm>
    377 
    378         <refnamediv>
    379           <refname>*ALTIVEC-AVAILABLE*</refname>
    380           <refpurpose></refpurpose>
    381           <refclass>Variable</refclass>
    382         </refnamediv>
    383 
    384         <refsect1>
    385           <title>Description</title>
    386           <para>This variable is intitialized each time an &CCL; session
    387           starts based on information provided by the lisp kernel. Its value
    388           is true if AltiVec is present and false otherwise. This variable
    389           shouldn't be set by user code.</para>
    390         </refsect1>
     388            <indexterm zone="v_altivec-available">
     389              <primary>*altivec-available*</primary>
     390            </indexterm>
     391
     392            <refnamediv>
     393              <refname>*ALTIVEC-AVAILABLE*</refname>
     394              <refpurpose></refpurpose>
     395              <refclass>Variable</refclass>
     396            </refnamediv>
     397
     398            <refsect1>
     399              <title>Description</title>
     400              <para>This variable is initialized each time an &CCL; session
     401                starts based on information provided by the lisp kernel. Its value
     402                is true if AltiVec is present and false otherwise. This variable
     403                shouldn't be set by user code.</para>
     404            </refsect1>
    391405      </refentry>
    392406
    393407      <refentry id="f_altivec-available-p">
    394         <indexterm zone="f_altivec-available-p">
    395           <primary>altivec-available-p</primary>
    396         </indexterm>
    397 
    398         <refnamediv>
    399           <refname>ALTIVEC-AVAILABLE-P</refname>
    400           <refpurpose></refpurpose>
    401           <refclass>Function</refclass>
    402         </refnamediv>
    403        
    404         <refsynopsisdiv>
    405           <synopsis><function>altivec-available-p</function></synopsis>
    406         </refsynopsisdiv>
    407 
    408         <refsect1>
    409           <title>Description</title>
    410 
    411           <para>Returns non-NIL if AltiVec is available.</para>
    412         </refsect1>
     408            <indexterm zone="f_altivec-available-p">
     409              <primary>altivec-available-p</primary>
     410            </indexterm>
     411
     412            <refnamediv>
     413              <refname>ALTIVEC-AVAILABLE-P</refname>
     414              <refpurpose></refpurpose>
     415              <refclass>Function</refclass>
     416            </refnamediv>
     417           
     418            <refsynopsisdiv>
     419              <synopsis><function>altivec-available-p</function></synopsis>
     420            </refsynopsisdiv>
     421
     422            <refsect1>
     423              <title>Description</title>
     424
     425              <para>Returns non-NIL if AltiVec is available.</para>
     426            </refsect1>
    413427      </refentry>
    414428
    415429      <refentry id="v_altivec-lapmacros-maintain-vrsave-p">
    416         <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
    417           <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
    418         </indexterm>
    419 
    420         <refnamediv>
    421           <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
    422           <refpurpose></refpurpose>
    423           <refclass>Variable</refclass>
    424         </refnamediv>
    425        
    426         <refsect1>
    427           <title>Description</title>
    428 
    429           <para>Intended to control the expansion of certain lap macros.
    430           Initialized to NIL on LinuxPPC; initialized to T on platforms
    431           (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
    432           a bitmask of active vector registers at all times.</para>
    433         </refsect1>
     430            <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
     431              <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
     432            </indexterm>
     433
     434            <refnamediv>
     435              <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
     436              <refpurpose></refpurpose>
     437              <refclass>Variable</refclass>
     438            </refnamediv>
     439           
     440            <refsect1>
     441              <title>Description</title>
     442
     443              <para>Intended to control the expansion of certain lap macros.
     444                Initialized to NIL on LinuxPPC; initialized to T on platforms
     445                (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
     446                a bitmask of active vector registers at all times.</para>
     447            </refsect1>
    434448      </refentry>
    435449
    436450      <refentry id="lapm_with-altivec-registers">
    437         <indexterm zone="lapm_with-altivec-registers">
    438           <primary>with-altivec-registers</primary>
    439         </indexterm>
    440 
    441         <refnamediv>
    442           <refname>WITH-ALTIVEC-REGISTERS</refname>
    443           <refpurpose></refpurpose>
    444           <refclass>LAP Macro</refclass>
    445         </refnamediv>
    446 
    447         <refsynopsisdiv>
    448           <synopsis><function>with-altivec-registers</function>
    449           reglist &body; body</synopsis>
    450         </refsynopsisdiv>
    451 
    452         <refsect1>
    453           <title>Arguments and Values</title>
    454 
    455           <variablelist>
    456             <varlistentry>
    457               <term>reglist</term>
    458 
    459               <listitem>
    460                 <para>A list of vector register names (vr0 .. vr31).</para>
    461               </listitem>
    462             </varlistentry>
    463 
    464             <varlistentry>
    465               <term>body</term>
    466 
    467               <listitem>
    468                 <para>A sequence of PPC LAP instructions.</para>
    469               </listitem>
    470             </varlistentry>
    471           </variablelist>
    472         </refsect1>
    473 
    474         <refsect1>
    475           <title>Description</title>
    476 
    477           <para>Specifies the set of AltiVec registers used in body. If
    478           *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
    479           expanded, generates code to save the VRSAVE SPR and updates VRSAVE
    480           to incude a bitmask generated from the specified register list.
    481           Generates code which saves any non-volatile vector registers which
    482           appear in the register list, executes body, and restores the saved
    483           non-volatile vector registers (and, if
    484           *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
    485           well. Uses the IMM0 register (r3) as a temporary.</para>
    486         </refsect1>
     451            <indexterm zone="lapm_with-altivec-registers">
     452              <primary>with-altivec-registers</primary>
     453            </indexterm>
     454
     455            <refnamediv>
     456              <refname>WITH-ALTIVEC-REGISTERS</refname>
     457              <refpurpose></refpurpose>
     458              <refclass>LAP Macro</refclass>
     459            </refnamediv>
     460
     461            <refsynopsisdiv>
     462              <synopsis><function>with-altivec-registers</function>
     463                reglist &body; body</synopsis>
     464            </refsynopsisdiv>
     465
     466            <refsect1>
     467              <title>Arguments and Values</title>
     468
     469              <variablelist>
     470                <varlistentry>
     471                  <term>reglist</term>
     472
     473                  <listitem>
     474                        <para>A list of vector register names (vr0 .. vr31).</para>
     475                  </listitem>
     476                </varlistentry>
     477
     478                <varlistentry>
     479                  <term>body</term>
     480
     481                  <listitem>
     482                        <para>A sequence of PPC LAP instructions.</para>
     483                  </listitem>
     484                </varlistentry>
     485              </variablelist>
     486            </refsect1>
     487
     488            <refsect1>
     489              <title>Description</title>
     490
     491              <para>Specifies the set of AltiVec registers used in body. If
     492                *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
     493                expanded, generates code to save the VRSAVE SPR and updates VRSAVE
     494                to include a bitmask generated from the specified register list.
     495                Generates code which saves any non-volatile vector registers which
     496                appear in the register list, executes body, and restores the saved
     497                non-volatile vector registers (and, if
     498                *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
     499                well. Uses the IMM0 register (r3) as a temporary.</para>
     500            </refsect1>
    487501      </refentry>
    488502
    489503      <refentry id="lapm_with-vector-buffer">
    490         <indexterm zone="lapm_with-vector-buffer">
    491           <primary>with-vector-buffer</primary>
    492         </indexterm>
    493 
    494         <refnamediv>
    495           <refname>WITH-VECTOR-BUFFER</refname>
    496           <refpurpose></refpurpose>
    497           <refclass>LAP Macro</refclass>
    498         </refnamediv>
    499        
    500         <refsynopsisdiv>
    501           <synopsis>with-vector-buffer base n &body; body</synopsis>
    502         </refsynopsisdiv>
    503 
    504         <refsect1>
    505           <title>Arguments and Values</title>
    506 
    507           <variablelist>
    508             <varlistentry>
    509               <term>base</term>
    510 
    511               <listitem>
    512                 <para>Any available general-purpose register.</para>
    513               </listitem>
    514             </varlistentry>
    515 
    516             <varlistentry>
    517               <term>n</term>
    518 
    519               <listitem>
    520                 <para>An integer between 1 and 254, inclusive. (Should
    521                 typically be much, much closer to 1.) Specifies the size of
    522                 the buffer, in 16-byte units.</para>
    523               </listitem>
    524             </varlistentry>
    525 
    526             <varlistentry>
    527               <term>body</term>
    528 
    529               <listitem>
    530                 <para>A sequence of PPC LAP instructions.</para>
    531               </listitem>
    532             </varlistentry>
    533           </variablelist>
    534         </refsect1>
    535 
    536         <refsect1>
    537           <title>Description</title>
    538           <para>Generates code which allocates a 16-byte aligned buffer
    539           large enough to contain N vector registers; the GPR base points to
    540           the lowest address of this buffer. After processing body, the
    541           buffer will be deallocated. The body should preserve the value of
    542           base as long as it needs to reference the buffer. It's
    543           intended that base be used as a base register in stvx and lvx
    544           instructions within the body.</para>
    545         </refsect1>
     504            <indexterm zone="lapm_with-vector-buffer">
     505              <primary>with-vector-buffer</primary>
     506            </indexterm>
     507
     508            <refnamediv>
     509              <refname>WITH-VECTOR-BUFFER</refname>
     510              <refpurpose></refpurpose>
     511              <refclass>LAP Macro</refclass>
     512            </refnamediv>
     513           
     514            <refsynopsisdiv>
     515              <synopsis>with-vector-buffer base n &body; body</synopsis>
     516            </refsynopsisdiv>
     517
     518            <refsect1>
     519              <title>Arguments and Values</title>
     520
     521              <variablelist>
     522                <varlistentry>
     523                  <term>base</term>
     524
     525                  <listitem>
     526                        <para>Any available general-purpose register.</para>
     527                  </listitem>
     528                </varlistentry>
     529
     530                <varlistentry>
     531                  <term>n</term>
     532
     533                  <listitem>
     534                        <para>An integer between 1 and 254, inclusive. (Should
     535                          typically be much, much closer to 1.) Specifies the size of
     536                          the buffer, in 16-byte units.</para>
     537                  </listitem>
     538                </varlistentry>
     539
     540                <varlistentry>
     541                  <term>body</term>
     542
     543                  <listitem>
     544                        <para>A sequence of PPC LAP instructions.</para>
     545                  </listitem>
     546                </varlistentry>
     547              </variablelist>
     548            </refsect1>
     549
     550            <refsect1>
     551              <title>Description</title>
     552              <para>Generates code which allocates a 16-byte aligned buffer
     553                large enough to contain N vector registers; the GPR base points to
     554                the lowest address of this buffer. After processing body, the
     555                buffer will be deallocated. The body should preserve the value of
     556                base as long as it needs to reference the buffer. It's
     557                intended that base be used as a base register in stvx and lvx
     558                instructions within the body.</para>
     559            </refsect1>
    546560      </refentry>
    547561    </sect1>
Note: See TracChangeset for help on using the changeset viewer.