source: trunk/source/doc/src/modifying.xml @ 8820

Last change on this file since 8820 was 8820, checked in by jaj, 12 years ago

This commit includes support for docbook 4.5, stylesheet changes, and updated documentation.

In order to support docbook 4.5 in nXML mode, I have added a new directory called docbook-rng-4.5 and changed schemas.xml to point to it. This should just work when editing the documentation in EMACS.

The two most obvious changes to the stylesheets are that the table of contents for each chapter now occurs at the beginning of the chapter, and the format for refentries is cleaner and more concise.

I think that we should consistently use refentry elements for all of the definitions of functions, macros, variables, etc. This retains the structured data for the definitions that can be reformatted to have different appearences by the stylesheets. We should also consistently use other docbook elements such as function and varname. I'm not really happy with their appearance right now, but that can be easily tweaked in the stylesheets as long as they are consistently used throughout the documentation.

File size: 20.8 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY rest "<varname>&amp;rest</varname>">
4<!ENTITY key "<varname>&amp;key</varname>">
5<!ENTITY optional "<varname>&amp;optional</varname>">
6<!ENTITY body "<varname>&amp;body</varname>">
7<!ENTITY aux "<varname>&amp;aux</varname>">
8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9<!ENTITY CCL "Clozure CL">
10]>
11
12  <chapter id="Modifying-CCL">
13    <title>Modifying &CCL;</title>
14
15    <sect1 id="Contributing-Code-Back-to-the-CCL-Project">
16      <title>Contributing Code Back to the &CCL; Project</title>
17      <para>This section is a placeholder, added as of August 2004.  The
18      full text is being written, and will be added as soon as it is
19      available.</para>
20    </sect1>
21
22    <sect1 id="Using-CCL-in--development--and-in--user--mode">
23      <title>Using &CCL; in "development" and in  "user" mode</title>
24
25      <para>As it's distributed, &CCL; starts up with *PACKAGE* set
26      to the CL-USER package and with most predefined functions and
27      methods protected against accidental redefinition.  The package
28      setting is of course a requirement of ANSI CL, while the
29      protection protection is intended to catch certain types of
30      programming errors (accidentally redefining a CL or CCL
31      function) before those errors have a chance to do much
32      damage.</para>
33      <para>These settings may make using &CCL; to develop &CCL; a
34      bit more awkward, since much of that process assumes that the
35      CCL package is current (and a primary purpose of that process is
36      to redefine some "predefined, builtin functions".) The standard,
37      "routine" ways of building &CCL; from sources (see ) -
38      COMPILE-CCL, XCOMPILE-CCL, and XLOAD-LEVEL-0 - bind *PACKAGE* to
39      the "CCL" package and enable the redefinition of predefined
40      functions; the symbols COMPILE-CCL, XCOMPILE-CCL, and
41      XLOAD-LEVEL-0 are additionally now exported from the "CCL"
42      package.</para>
43      <para>Some other (more ad-hoc) ways of doing development on
44      &CCL; - compiling and/or loading individual files,
45      incrementally redefining individual functions - may be awkward
46      unless one reverts to the mode of operation which was
47      traditionally offered in &CCL;. (Some &CCL; source files -
48      especially those that comprise the bootstrapping image sources
49      and the first few files in the "cold load" sequence - are
50      compiled and loaded in the "CCL" package but don't contain
51      (IN-PACKAGE "CCL") forms, since IN-PACKAGE doesn't work until
52      later in the cold load sequence.)</para>
53      <para>The somewhat bizarre behavior of both SET-USER-ENVIRONMENT
54      and SET-DEVELOPMENT-ENVIRONMENT with respect to the special
55      variables they affect is intended to allow those constructs to
56      take effect when the read-eval-print loop next returns to a
57      top-level '? ' prompt; the constructs can meaningfully be used
58      inside LOAD, for instance (recall that LOAD binds *PACKAGE*),
59      though using both constructs within the same LOAD call would
60      likely be pretty confusing.</para>
61      <para>"user" and "development" are otherwise very generic terms;
62      here they're intended to enforce the distinction between "using"
63      &CCL; and "developing" it.</para>
64      <para>The initial environment from which &CCL; images are
65      saved is one where (SET-USER-ENVIRONMENT T) has just been
66      called; in previous versions, it was effectively as if
67      (SET-DEVELOPMENT-ENVIRONMENT T) had just been called.</para>
68      <para>Hopefully, most users of &CCL; can safely ignore these
69      issues most of the time. Note that doing (SET-USER-ENVIRONMENT
70      T) after loading one's own code (or 3rd-party code) into &CCL;
71      would protect that code (as well as &CCL;'s) from accidental
72      redefinition; that may be useful in some cases.</para>
73    </sect1>
74
75    <sect1 id="Debugging-facilities-in-the-lisp-kernel">
76      <title>Debugging facilities in the lisp kernel</title>
77      <para> In a perfect world, something like this couldn't
78      happen:</para>
79      <programlisting>
80Welcome to &CCL; Version x.y!
81? (defun foo (x)
82    (declare (cons x))
83    (cdr x))
84FOO
85
86? (foo -1) ;Oops. Too late ...
87Unhandled exception 11 at 0x300e90c8, context->regs at #x7ffff6b8
88Continue/Debugger/eXit &lt;enter&gt;?
89</programlisting>
90      <para>As you may have noticed, it's not a perfect world; it's rare
91that the cause (attempting to reference the CDR of -1, and therefore
92accessing unmapped memory near location 0) of this effect (an
93"Unhandled exception ..." message) is so obvious.</para>
94      <para>The addresses printed in the message above aren't very useful
95unless you're debugging the kernel with GDB (and they're often
96very useful if you are.)</para>
97      <para>Aside from causing an exception that the lisp kernel doesn't
98know how to handle, one can also enter the kernel debugger (more)
99deliberately:</para>
100      <programlisting>
101? (defun classify (n)
102     (cond ((&gt; n 0) "Greater")
103           ((&lt; n 0) "Less")
104           (t
105            ;;; Sheesh ! What else could it be ?
106            (ccl::bug "I give up. How could this happen ?"))))
107CLASSIFY
108
109? (classify 0)
110Bug in &CCL; system code:
111I give up. How could this happen ?
112? for help
113[12345] &CCL; kernel debugger:
114      </programlisting>
115      <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>
124      <para>If one enters a '?' at the kernel debugger prompt, one
125      will see output like:</para>
126      <programlisting>
127(S)  Find and describe symbol matching specified name
128(B)  Show backtrace
129(X)  Exit from this debugger, asserting that any exception was handled
130(K)  Kill &CCL; process
131(?)  Show this help
132</programlisting>
133      <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>
142      <programlisting>
143? (defun classify2 (n)
144  (cond ((&gt; n 0) "Greater")
145        ((&lt; n 0) "Less")
146        (t (dbg n))))
147CLASSIFY2
148
149? (classify2 0)
150Lisp Breakpoint
151 While executing: #&lt;Function CLASSIFY2 #x08476cfe>
152? for help
153[12345] &CCL; kernel debugger: ?
154(G)  Set specified GPR to new value
155(A)  Advance the program counter by one instruction (use with caution!)
156(D)  Describe the current exception in greater detail
157(R)  Show raw GPR/SPR register values
158(L)  Show Lisp values of tagged registers
159(F)  Show FPU registers
160(S)  Find and describe symbol matching specified name
161(B)  Show backtrace
162(X)  Exit from this debugger, asserting that any exception was handled
163(P)  Propagate the exception to another handler (debugger or OS)
164(K)  Kill &CCL; process
165(?)  Show this help
166</programlisting>
167      <para>CCL::DBG takes an argument, whose value is copied into the register
168that &CCL; uses to return a function's primary value (arg_z, which
169is r23 on the PowerPC). If we were to choose the (L) option at this point,
170we'd see a dislay like:</para>
171      <programlisting>rnil = 0x01836015
172nargs = 0
173r16 (fn) = #&lt;Function CLASSIFY2 #x30379386>
174r23 (arg_z) = 0
175r22 (arg_y) = 0
176r21 (arg_x) = 0
177r20 (temp0) = #&lt;26-element vector subtag = 2F @#x303793ee>
178r19 (temp1/next_method_context) = 6393788
179r18 (temp2/nfn) = #&lt;Function CLASSIFY2 #x30379386>
180r17 (temp3/fname) = CLASSIFY2
181r31 (save0) = 0
182r30 (save1) = *TERMINAL-IO*
183r29 (save2) = 0
184r28 (save3) = (#&lt;RESTART @#x01867f2e> #&lt;RESTART @#x01867f56>)
185r27 (save4) = ()
186r26 (save5) = ()
187r25 (save6) = ()
188r24 (save7) = ()
189</programlisting>
190      <para>From this we can conclude that the problematic argument to CLASSIFY2
191was 0 (see r23/arg_z), and that I need to work on a better example.</para>
192      <para>The R option shows the values of the ALU (and PPC branch unit)
193registers in hex; the F option shows the values of the FPU registers.</para>
194      <para>The (B) option shows a raw stack backtrace; it'll try to
195identify foreign functions as well as lisp functions. (Foreign function
196names are guesses based on the nearest preceding exported symbol.)</para>
197      <para>If you ever unexpectedly find yourself in the "lisp kernel
198debugger", the output of the (L) and (B) options are often the most
199helpful things to include in a bug report.</para>
200    </sect1>
201
202    <sect1 id="Using-AltiVec-in-CCL-LAP-functions">
203      <title>Using AltiVec in &CCL; LAP functions</title>
204
205      <sect2 id="Overview--16-">
206        <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>
226      </sect2>
227
228      <sect2 id="Register-usage-conventions">
229        <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
247vector registers (vr20 .. vr31) before assigning to them and to restore
248such registers before returning to the caller.</para>
249        <para>On platforms that require that VRSAVE be maintained, it's not
250necessary to mention the "use" of vector registers that're
251used as incoming parameters. It's not incorrect to mention their use
252in a WITH-ALTIVEC-REGISTERS form, but it may be unneccessary in many
253interesting cases. One can likewise assume that the caller of any function
254that returns a vector value (in vr2 has already set the apropriate bit in
255VRSAVE to indicate that this register is live. One could therefore write a
256leaf function that added the bytes in vr3 and vr2 and returned the result
257in vr2 as:</para>
258        <programlisting>
259(defppclapfunction vaddubs ((y vr3) (z vr2))
260  (vaddubs z y z)
261  (blr))
262</programlisting>
263        <para>When vector registers that aren't incoming parameters are used
264in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
265and of saving/restoring any non-volatile vector registers:</para>
266        <programlisting>
267(defppclapfunction load-array ((n arg_z))
268  (check-nargs 1)
269  (with-altivec-registers (vr1 vr2 vr3 vr27) ; Clobbers imm0
270    (li imm0 arch::misc-data-offset)
271    (lvx vr1 arg_z imm0) ; load MSQ
272    (lvsl vr27 arg_z imm0) ; set the permute vector
273    (addi imm0 imm0 16) ; address of LSQ
274    (lvx vr2 arg_z imm0) ; load LSQ
275    (vperm vr3 vr1 vr2 vr27) ; aligned result appears in VR3
276    (dbg t)) ; Look at result in some debugger
277  (blr))
278</programlisting>
279        <para>AltiVec registers are not preserved by CATCH and UNWIND-PROTECT.
280Since AltiVec is only accessible from LAP in &CCL; and since LAP
281functions rarely use high- level control structures, this should rarely be
282a problem in practice.</para>
283        <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
285vector registers before such a call and restore them on return. This is
286one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
287      </sect2>
288    </sect1>
289
290    <sect1 id="Development-Mode-Dictionary">
291      <title>Development-Mode Dictionary</title>
292
293      <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>
315      </refentry>
316
317      <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>
344      </refentry>
345
346      <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>
372      </refentry>
373      <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>
391      </refentry>
392
393      <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>
413      </refentry>
414
415      <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>
434      </refentry>
435
436      <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>
487      </refentry>
488
489      <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>
546      </refentry>
547    </sect1>
548  </chapter>
Note: See TracBrowser for help on using the repository browser.