[Bug gas/20344] New: no docs for the .seh_* directives

[asbugzilla at limegreensocks dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=20344

            Bug ID: 20344
           Summary: no docs for the .seh_* directives
           Product: binutils
           Version: 2.26
            Status: UNCONFIRMED
          Severity: normal
          Priority: P2
         Component: gas
          Assignee: unassigned at sourceware dot org
          Reporter: asbugzilla at limegreensocks dot com
  Target Milestone: ---

There are no descriptions for the .seh_* directives in the 2.26 docs.

There were the beginnings of some docs in the original checkin thread
(https://sourceware.org/ml/binutils/2009-08/msg00193.html), but while the code
change happened, apparently the doc changes did not.  Also, it doesn't appear
to have been written by a native English speaker, so it could use some cleanup.

And while I know it's uncommon for 'as' docs to provide a 'usage' guide, google
didn't find me *anything* about how and when to use these.  Looking at the
formatting for 'CFI directives,' that seems like a good model.  But it needs to
include some more descriptive text.  Perhaps something like this:

-----------------
These directives should be used in x86_x64 targeting Windows (and Linux?) if
the executable will be using Structured Exception Handling.  They are
appropriate for use in stand-alone asm files, code generated by high level
languages (such as C/C++) as well as inline asm instructions from higher level
languages.

In general, any time the code modifies the stack (push, call, subq $32, %rsp,
etc) or stores a non-volatile register, you must use one of these directives so
that the necessary information gets added to the .xdata and .pdata sections of
the executable.

Some examples of common usage:

At the beginning of a function:

    .globl __argtos
    .seh_proc __argtos
__argtos:

When saving any (non-volatile?) general purpose register:

    push %rbp
    .seh_pushreg %rbp

When saving any (non-volatile?) xmm register:

    movaps %xmm6, (%rsp)
    .seh_savexmm %xmm6, 0

When creating a stack frame:

    mov  %rsp, %rbp
    .seh_setframe %rbp, 0

When reserving stack space:

    lea -(iOffset + iBytes)(%rsp), %rsp
    .seh_stackalloc iOffset + iBytes

When the function prolog is complete.  At this point, the stack should be
properly aligned according to the rules for the OS.

    .seh_endprologue

At the end of the function definition (which may come well after the 'ret'
instruction):

    .seh_endproc

??? gcc emits no directives for these stack modifying instructions:

    mov %rbp, %rsp
    pop %rbp

    ret

?? What do you use for stack alignment:

    andq $-16, %rsp

-----------------

I'm not sure what these are or how they are used:

.seh_handler
.seh_eh
.seh_32/.seh_no32
.seh_savereg (?same as .seh_pushreg but used when saved with mov instead of
push?)
.seh_savemm (?same as .seh_savexmm but used with mmx registers?)
.seh_scope

When I say 'something like this,' I don't mean exactly this.  This is my best
understanding of how these directives are used, but I am (obviously) no expert
on SEH.  But without some type of guide, no one can hope to use these
correctly.  And since 'as' is where these are implemented, it is the only
possible definitive source for this info.

Even as simple an intro-to-seh as this would be a huge help.

-- 
You are receiving this mail because:
You are on the CC list for the bug.