*** UNIX MANUAL PAGE BROWSER ***

pdsc(4) Kernel Interfaces Manual pdsc(4) NAME pdsc.h - Defines structures describing procedures conforming to the Calling Standard for Alpha Systems . SYNOPSIS #include <pdsc.h> DESCRIPTION The pdsc.h header file defines two basic data structures: the code range descriptor (crd) and the run-time procedure descriptor (rpd). Code range descriptors associate a contiguous sequence of addresses with a run-time procedure descriptor. This mapping can be many-to-one. Code range descriptors support optimizations (for example, reducing cache collisions) where all of the code for a procedure might not be contiguous. Run-time procedure descriptors provide unwind and excep- tion handler information about a procedure or part of a procedure. Several run-time procedure descriptors might be needed if a procedure has multiple entry points (as in FORTRAN). Currently, one code range descriptor exists for each run-time procedure descriptor. The assembler creates both the crds and rpds. Crds are stored alone in address order in the .pdata section of an object file. Rpds are stored along with language generated exception information in the .xdata section of an object file. The assembler supports an .edata 0 directive to allow the language or user to enter information into the .xdata section. The .end assembler directive, which denotes the end of a procedure, tells the assembler to generate the crd and rpd for the ended proce- dure. The .xdata and .pdata sections are coalesced in order from multiple re- locatable objects and non-shared libraries by the linker into one large .xdata and one large .pdata section for each executable or shared ob- ject. The linker adds an extra element to the code range descriptors, whose address is one address beyond the end of the text segment. For a diagram of a code range descriptor, see the pdsc.h file. The begin_address field is shifted left 2 bits. Its position is rela- tive to the beginning of the whole code range descriptor table. This shift enables a binary search of these addresses. (If they were self relative like rpd_offset, you have to calculate the actual address be- fore being able to do the compare.) This field definition restricts the code range to be within 32 bits of the code range descriptor table. This field is the first address of a code range. The begin_address of the next crd is one address beyond the bounds the code range from the top. As stated above, the linker adds a last element. The rpd_offset is a self-relative field that points to the run-time procedure descriptor entry for this code range. This field definition restricts the run-time procedure descriptor to be within 32 bits of the code range descriptor table. The rpd_offset field might equal zero if the procedure is a null frame whose entry_ra is $26 and contains no handler and PDSC_FLAGS_REGISTER_FRAME is set. This condition implies no separate procedure descriptor. The prologue bit is set if the code range does not contain a prologue. This information is important in determining which register to restore during an unwind operation. All the structure definitions have simple typedefs to define the fields in case they need to have idfefs processed to differentiate the code on the basis of the hardware architecture. See the pdsc.h header file for their specific definitions. The pdsc.h header file provides a union that allows for accessing the two main fields as 32 bit items. The header file also provides macros to help use those 32 bit items. The union definition for code range descriptors follows: /* * Runtime Code Range Descriptor */ typedef union pdsc_crd { struct { pdsc_offset begin_address; /* offst to 1st address in range */ pdsc_offset rpd_offset; /* offst to rpd including bits */ } words; struct { pdsc_space reserved1:2; /* must be 0 */ pdsc_offset shifted_begin_address:30; /* shifted left 2 */ pdsc_mask no_prolog:1; /* flag */ pdsc_space reserved2:1; /* must be 0 */ pdsc_offset shifted_rpd_offset:30; /* shifted left 2 */ } fields; } pdsc_crd; Run-time procedure descriptors come in a number of variations. The DIGITAL UNIX operating system supports a short form and a long form and each may or may not have handler information. DIGITAL UNIX supports a short form (and the no procedure descriptor form mentioned in the code range descriptors discussion) to minimize the space required for excep- tion and unwind information. DIGITAL UNIX supports a long form for procedures whose information overflows the fields in the short form. DIGITAL UNIX also supports register frames that do not manifest a stack frame and may use temporary registers to save the ra. Manual collusion between a caller and callee is required to support the use of temporary registers for intrinsic and library functions to save the cost of stores and restores to and from memory. See the pdsc.h header file for diagrams of the short and long forms of the descriptors. The pdsc.h header file provides a union that embodies the different op- tions discussed above. The union definition for run-time procedure de- scriptors is: typedef union pdsc_rpd { struct pdsc_short_stack_rpd { pdsc_uchar_mask flags:8; /* information about frame */ pdsc_uchar_offset rsa_offset; /* savregs offst in quadwords */ pdsc_uchar_mask fmask:8; /* floating point reg mask */ pdsc_uchar_mask imask:8; /* integer register mask */ pdsc_count frame_size:16; /* frame size in 64 bit words */ pdsc_offset sp_set:8; /* instofset to inst which sets sp */ pdsc_count entry_length:8; /* # of insts in prologue */ } short_stack_rpd; struct pdsc_short_reg_rpd { pdsc_uchar_mask flags:8; /* information about frame */ pdsc_space reserved1:3; /* must be zero */ pdsc_register entry_ra:5; /* what contains ra on entry */ pdsc_register save_ra:5; /* entry_ra here after the prologue */ pdsc_space reserved2:11; /* must be zero */ pdsc_count frame_size:16; /* frame size in 64 bit words */ pdsc_offset sp_set:8; /* instofset to inst which sets sp */ pdsc_count entry_length:8; /* # of insts in prologue */ } short_reg_rpd; struct pdsc_long_stack_rpd { pdsc_mask flags:11; /* information about frame */ pdsc_register entry_ra:5; /* where ret pc is on entry */ pdsc_ushort_offset rsa_offset; /* saveregs offst in quadwords */ pdsc_offset sp_set:16; /* instofset to inst which sets sp */ pdsc_count entry_length:16; /* # of insts in prologue */ pdsc_count frame_size; /* frame size in quadwords */ pdsc_space reserved; /* must be zero */ pdsc_mask imask; /* integer register mask */ pdsc_mask fmask; /* floating point register mask */ } long_stack_rpd; struct pdsc_long_reg_rpd { pdsc_mask flags:11; /* information about frame */ pdsc_register entry_ra:5; /* where ret pc is on entry */ pdsc_register save_ra:5; /* we moved entry_ra in the prologue */ pdsc_space reserved1:11; /* must be zero */ pdsc_offset sp_set:16; /* instofset to inst which sets sp */ pdsc_count entry_length:16; /* # of insts in prologue */ pdsc_count frame_size; /* frame size in quadwords */ pdsc_space reserved2; /* must be zero */ pdsc_mask imask; /* integer register mask */ pdsc_mask fmask; /* floating point register mask */ } long_reg_rpd; struct pdsc_short_with_handler { union { struct pdsc_short_stack_rpd short_stack_rpd; /* base stack rpd */ struct pdsc_short_reg_rpd short_reg_rpd; /* base stack rpd */ } stack_or_reg; pdsc_address handler; /* optional handler address */ pdsc_address handler_data; /* optional handler data */ } short_with_handler; struct pdsc_long_with_handler { union { struct pdsc_long_stack_rpd long_stack_rpd; /* base stack rpd */ struct pdsc_long_reg_rpd long_reg_rpd; /* base stack rpd */ } stack_or_reg; pdsc_address handler; /* optional handler address */ pdsc_address handler_data; /* optional handler data */ } long_with_handler; } pdsc_rpd; /* runtime procedure descriptor */ As noted in the preceding code fragment, the flags field is a different length depending on whether a long or short descriptor is used. Conse- quently, the most used flags are grouped together so that they fit in the short frame. Use the PDSC_FLAGS_EXCEPTION_FRAME flag to trace back over signal frames. The PDSC_FLAGS_EXTENDER flag is not yet implemented and is reserved The header file defines a set of macros that easily enable users to ac- cess fields. Some macros provide support so users do not have to know whether they are using a short or long descriptor or even a stack frame as opposed to a register frame. The header file will also normalize the fields between descriptor types (for example, the register mask will be expanded to 32 bits). A null value for the rpd argument can cause some of the macros to pro- vide the default values. This provision of default values supports the case where the pdsc_crd does not point at any rpd and is denoted by No rpd. In the following table, each macro carries a PDSC_ prefix, which is omitted in the table to conserve space. Where there is no default value (such as for a handler), a zero (0) is returned when the value is not present. In the second column, Support, N means no rpd, S means support for stack, R means support for register, H means support for short, and L means support for long. tab(@); lfHB lfHB lfHB lfHB llll. _ PDSC_ Macro@Support@Arg@Comments _ SHORT_RPD_SIZE@@None@Size of a short without @@@handler information. LONG_RPD_SIZE@@None@Size of a long without @@@handler information. DEFAULT_ENTRY_RA@@None@$26, the default return @@@address register. RPD_SHORT@SRHL@&rpd@1 if it is a short rpd; @@@otherwise 0. RPD_REGISTER@SRHL@&rpd@1 if it is a register frame; @@@otherwise 0. RPD_HAS_HANDLER@SRHL@&rpd@1 if there is handler @@@information; other- wise 0. RPD_FLAGS@SRHL@&rpd@Flags field. RPD_RSA_OFFSET_FIELD@NSRHL@&rpd@rsa_offset field value. RPD_RSA_OFFSET@NSRHL@&rpd@rsa_offset in bytes. RPD_SAVE_RA@NSRHL@&rpd@save ra register. RPD_ENTRY_RA@NSRHL@&rpd@entry ra register. RPD_SIZE_FIELD@NSRHL@&rpd@frame_size field value. RPD_SIZE@NSRHL@&rpd@Frame size in bytes. RPD_SP_SET_FIELD@NSRHL@&rpd@sp_set field value. RPD_SP_SET@NSHRL@&rpd@sp_set offset in bytes. RPD_ENTRY_LENGTH_FIELD@NSHRL@&rpd@entry_length @@@field value. RPD_ENTRY_LENGTH@NSHRL@&rpd@Prologue size in bytes. RPD_IMASK@NSHRL@&rpd@32 bit saved int @@@register mask. RPD_FMASK@NSHRL@&rpd@32 bit saved fp @@@register mask. RPD_HANDLER@NSHRL@&rpd@Handler address. RPD_HANDLER_DATA@NSHRL@&rpd@Handler data address. CRD_OFFSET_MASK@@none@Masks off the lsb two bits. CRD_NO_PROLOG_MASK@@none@Masks all but the lsb bit. CRD_PRPD@@&crd@Pointer to the rpd for @@@this crd. CRD_CONTAINS_PROLOG@@&crd@1 if it does; @@@0 if not. CRD_BEGIN_ADRESS_FIELD@@&crd@Begin address field value. CRD_BEGIN_ADDRESS@@&.pdata@ptr to the first address @@@in the code range. @@&crd@ INST_OFFSET_SHIFT@@@Amounts to << insts to @@@a get # of bytes. FRAME_SIZE_SHIFT@@@Amounts to << frame siz @@@to a get # of bytes SHORT_RPD_IMASK_SHIFT@@@Amounts to << short imsk @@@to the position bits. SHORT_RPD_FMASK_SHIFT@@@Amounts to << short fmsk @@@to the position bits. _ RELATED INFORMATION exception_intro(3) delim off pdsc(4)