У всех директив ассемблера GNU (далее для краткости as) имена начинаются с точки ('.'). Остальная часть имени директивы это буквы, обычно маленькие в нижнем регистре (маленькие).

В этом переводе документации [1] обсуждаются директивы, которые доступны независимо от конфигурации машины (от target) для as. В конфигурациях некоторых машин имеются дополнительные директивы, см. врезки в конце статьи.

.abort

Эта директива немедленно останавливает ассемблирование. Она присутствует для совместимости с другими ассемблерами. Оригинальная идея была в том, что в ассемблер будет перенаправлен вывод из компилятора языка более высокого уровня. Если отправитель закрывает обработку и производит выход, он может использовать эту директиву, которая указывает ассемблеру, что он тоже должен выйти. В один прекрасный день директива .abort больше не будет поддерживаться.

.ABORT

Когда генерируется вывод COFF, as воспринимает эту директиву как синоним '.abort'.

Когда генерируется вывод b.out, as принимает эту директиву, но игнорирует её.

.align выражение1, выражение2, выражение3

Установит счетчик местоположения (в текущей подсекции) на определенную границу памяти. Первым выражением (которое должно быть абсолютным) является требуемое выравнивание, как описано ниже.

Второе выражение (также абсолютное) дает значение заполнения, которое должно быть сохранено в байтах заполнения. Это второе выражение (и запятая) может быть опущено. Если опущено, то байты дополнения нормально нулевые. Однако на некоторых системах, если секция помечена как содержащая код, и значение заполнения опущено, то пространство заполняется инструкциями пустой операции (no-op, NOP).

Третье выражение также абсолютное, и также необязательное. Если оно присутствует, то это максимальное количество байт, которое должно быть пропущено этой директивой выравнивания. Если для выполнения выравнивания потребуется пропустить больше байтов, чем указанный в третьем выражении максимум, то выравнивание не выполняется вообще. Можно полностью опустить значение заливки (второй аргумент), просто используя две запятые после требуемого выравнивания выражения 1; это может быть полезно, если требуется, чтобы выравнивание было заполнено инструкциями no-op, когда это необходимо.

Способ указания требуемого выравнивания зависит от конкретной системы. Для архитектур a29k, hppa, m68k, m88k, w65, sparc, Hitachi SH и i386 при использовании формата ELF, первое выражение это запрашиваемое выравнивание в байтах. Например, .align 8 увеличит счетчик позиции начала области, пока он не начнет нацело делиться на 8. Если текущая позиция уже и так делится на 8, то никакое изменение не нужно.

Для других систем, включая i386 при использовании формата a.out, выражение1 указывает количество равных 0 младших бит адреса, которые должны быть после выравнивания. Например, .align 3 увеличат текущее положение области памяти до тех пор, пока её адрес не будет нацело делиться на 8 (в таком адресе 3 младших бита равны 0). Если текущее положение и так уже нацело делится на 8, то никакого изменения начального адреса с целью выравнивания не требуется.

Эта несогласованность обусловлена разным поведением различных собственных ассемблеров для этих систем, которые ассемблер GNU должен эмулировать. Ассемблер GNU также предоставляет директивы .balign и .p2align, описанные ниже, которые имеют согласованное поведение во всех архитектурах (но они специфичны для GAS).

.app-file string

Директива .app-file (которая может быть также записана как '.file') говорит для as, что мы собирается запустить новый логический файл. Здесь string это имя нового файла. Как правило имя файла распознается независимо от того, окружено ли оно кавычками " или нет. Однако если вы хотите указать разрешенное пустое имя файла, то должны указать двойные кавычки "". В будущем этот оператор может уйти: он распознается только для совместимости со старыми версиями as.

.ascii "string"...

Директива .ascii ожидает ноль или большее количество строковых литералов (см. далее секцию "Strings" врезки "Символьные константы"), отделенных друг от друга запятыми. Каждая такая строка ассемблируется (без автоматического добавления в конец нулевого байта) в последовательные адреса.

.asciz "string"...

Директива .asciz подобна директиве .ascii, однако отличается тем, что строка ассемблируется с добавлением в конец нулевого байта.

.balign[wl] abs-expr1, abs-expr2, abs-expr3

Это директива выравнивания (alignment), она дополняет счетчик размещения (location counter) в текущей подсекции памяти до определенной границы. Первое выражение abs-expr1 (которое должно быть абсолютным значением) запрашивает размер выравнивания в байтах. Например, '.balign 8' увеличивает счетчик размещения до позиции адреса, который нацело делится на 8 (если адрес позиции счетчика размещения уже делится на 8, то никакого изменения счетчика размещения не требуется, и адрес текущей позиции размещения не меняется).

Второе выражение abs-expr2 (также абсолютное) указывает значение для байт заполнения. Этот параметр (и запятая перед ним) может быть опущен, тогда байты дополнения будут нулями. Однако в некоторых системах, если если секция помечена как содержащая код, и значение заполнения abs-expr2 опущено, то для заполнения используются данные инструкции no-op (нет операции).

Третье выражение abs-expr3 также абсолютное, и также опциональное. Если оно присутствует, то то оно указывает максимальное количество байт, которое должно быть пропущено этой директивой выравнивания alignment directive. Если выполнение выравнивания требует большего количества байт, чем указанный в abs-expr3 максимум, то выравнивание вообще не производится. Вы можете опустить значение заполнения (второй аргумент abs-expr2), просто указав две запятые после значения требуемого выравнивания abs-expr1; это может быть полезным, если вы хотите заполнить байты выравнивания подходящей инструкцией no-op.

Директивы .balignw и .balignl являются вариантами директивы .balign. Директива .balignw рассматривает образец для заполнения как двухбайтовое слово. Директива .balignl обрабатывает образец для заполнения как четырехбайтное слово. Например, .balignw 4, 0x368d приведет к выравниванию счетчика адреса таким образом, что он будет нацело делиться на 4. Если выравнивание пропустит 2 байта, то они будут заполнены значением 0x368d (положение этих байт в памяти зависит от endianness процессора [5]). Если нужно пропустить для выравнивания 1 или 3 байта, то значение заполнения неопределенное.

.byte expressions

Директива .byte ожидает ноль или большее количество выражений (expressions), отделенных друг от друга запятой. Каждое выражение ассемблируется в следующий байт.

.comm symbol, length

Директива .comm декларирует общий (common) символ с именем symbol. При линковке общий символ в объектном файле может быть объединен с определенным или общим символом с тем же именем в другом объектном файле. Если линкер (ld) не видит определения для символа - только один или большее количество общих символов - то он выделяет в памяти length не инициализированных байт. Значение параметра length должно быть абсолютным выражением. Если ld видит несколько общих символов с одинаковым именем, но разной длиной length, то он выделит в памяти самое большое количество байт length.

Когда используется формат ELF, директива .comm принимает опциональный третий аргумент. Он определяет желаемое выравнивание symbol, указанное как байтовая граница (например, выравнивание 16 означает, что самые младшие значимые биты адреса должны быть равны 0). Выравнивание должно быть абсолютным выражением, и должно быть равно степени двойки. Если ld выделит неинициализированную память для общего символа, то будет он будет использовать выравнивание для размещения этого символа. Если выравнивание не указано, то его значение будет установлено на максимальное значение степени двойки, которое меньше или равно размеру символа length, до максимума 16.

На архитектуре HPPA синтаксис директивы .comm незначительно отличается: 'symbol .comm, length'; symbol здесь опционален.

.data subsection

Директива .data указывает as ассемблировать следующие операторы в конце пронумерованного подраздела данных subsection (этот параметр должен быть абсолютным выражением). Если параметр subsection опущен, то по умолчанию подразумевается 0.

.def name

Начало определения отладочной информации для символа с именем name; определение продолжается, пока не встретится директива .endef.

Эта директива обрабатывается только когда as сконфигурирован для генерации выходного формата COFF; когда генерируется формат b.out, директива '.def' распознается, но игнорируется.

.desc symbol, abs-expression

Эта директива установит дескриптор символа (см. секцию "Symbol Attributes" документации [6]) в младшие 16 бит абсолютного выражения abs-expression.

Директива '.desc' недоступна, когда as сконфигурирован на генерацию формата COFF; она работает только для объектного формата a.out или b.out. Для обеспечения совместимости as в режиме генерации COFF-формата принимает директиву '.desc', но не генерирует её вывод.

.dim

Эта директива генерируется компиляторами для включения отладочной информации в таблицу символов. Она разрешена только внутри пары .def/.endef.

Директива '.dim' имеет смысл только при генерации формата COFF; когда генерируется формат b.out, она принимается, но игнорируется.

.double flonums

Директива .double ожидает ноль или большее количество параметров flonums, отделенных друг от друга запятой. Она ассемблируется в данные чисел с плавающей точкой. Точный вид генерируемых чисел с плавающей точкой зависит от того, как сконфигурирован as (см. далее "Директивы, зависящие от целевого процессора).

.eject

Установит в этом месте разрыв страницы (page break), когда генерируются листинги ассемблера.

.else

Директива .else работает как часть поддержки as директив условного ассемблирования (conditional assembly), см далее описание директивы .if abs-expression. Директива .else пометит начало секции кода, которая будет ассемблироваться, когда предшествующее выражение директивы .if было вычислено как false.

.endef

Эта директива помечает конец определения символа, начинающееся на директиву .def.

Директива '.endef' имеет смысл только когда генерируется формат COFF; если as сконфигурирован на генерацию формата b.out, то она принимается, но игнорируется.

.endif

Директива .endif работает как часть поддержки as условного ассемблирования; она помечает конец блока кода, который ассемблируется по условию (.if/.else/.endif). См. описание директивы .if abs-expression.

.equ symbol, expression

Эта директива установит значение символа symbol в значение выражения expression. Она является синонимом '.set'; см. описание директивы .set symbol, expression.

Синтаксис equ на архитектуре HPPA: 'symbol .equ expression'.

.equiv symbol, expression

Директива .equiv подобна .equ и .set, отличие только в том, что ассемблер будет сигнализировать об ошибке, если символ уже был определен.

За исключением сообщения об ошибке, это примерно эквивалентно следующему:

.ifdef SYM

.err

.endif

.equ SYM,VAL

.err

Если as наткнулся на директиву .err, то он выведет сообщение об ошибке и, если не указана опция -Z, то объектный файл не сгенерируется. Это может использоваться для сигнала об ошибке в условно ассемблируемом коде (часто удобно для определения, какая ветка условных операторов .if/.else ассемблируется).

.extern

Директива .extern принимается в исходном коде программы для совместимости с другими ассемблерами, но игнорируется. Ассемблер as считает все неопределенные символы как external (внешние).

.file string

Директива .file (которая может быть также записана как '.app-file') говорит ассемблеру as, что мы собираемся начать новый логический файл. Параметр string это имя нового файла. Как правило имя файла распознается независимо от того, заключено ли оно в двойные кавычки ", или нет; однако если вы хотите указать пустое имя файла, то необходимо указать двойные кавычки: "". Этот оператор может уйти в будущем: он распознается только для совместимости со старыми версиями ассемблера as. В некоторых конфигурациях as директива .file уже удалена во избежание конфликтов с другими ассемблерами. См. также далее "Директивы, зависящие от целевого процессора".

.fill repeat, size, value

Параметры repeat, size и value это абсолютные выражения. Эта директива выдаст repeat раз повторяющихся копий size байт. Значение repeat может быть 0 или больше. Значение size может быть 0 или больше, но если оно больше 8, то подразумевается значение 8, чтобы обеспечить совместимость с другими ассемблерами. Содежимое каждой порции повторяющихся байт берется из 8-байтного числа. Старшие 4 байта нули. Младшие 4 байта имеют значение value, сформированное из принятого порядка байт (endianness) целевого процессора. Каждая порция size байт в повторении берутся из младших size байт этого числа. Опять же, такое странное поведение совместимо с ассемблерами других разработчиков.

Параметры size и value опциональны. Если вторая запятая и value отсутствуют, то значение для value подразумевается 0. Если первая запятая и последующие параметры отсутствуют, то подразумевается size равное 1.

.float flonums

Эта директива ассемблируется в 0 или большее количество чисел с плавающей запятой flonums, отделенных друг от друга запятой. Это дает тот же эффект, что и .single. Точный вид генерируемых данных для чисел с плавающей запятой зависит от того, как as сконфигурирован. См. также далее "Директивы, зависящие от целевого процессора".

.global symbol, .globl symbol

Директива .global делает символ symbol доступным для линкера ld. Если вы определили symbol в одной из своих частей программы, то его значение делается доступным для других линкуемых частей программы. В противном случае символ берет свои атрибуты из символа с тем же именем из другого файла, который линкуется в ту же программу.

Принимаются оба варианта директивы('.globl' и '.global'), для совместимости с другими ассемблерами.

На архитектуре HPPA директивы .global не всегда достаточно, чтобы сделать символ доступным для других частей программы. Вам также может понадобится директива .EXPORT, предназначенная только для HPPA. См. врезку "Функции, зависимые от HPPA".

.hword expressions

Эта директива принимает ноль или большее количество выражений expressions, и для каждого выдает 16-битное число.

Эта директива является синонимом директивы '.short'; в зависимости от целевой архитектуры она может быть и синонимом для '.word'.

.ident

Эта директива используется некоторыми ассемблерами, чтобы поместить теги в объектные файлы. Ассемблер as просто принимает эту директиву для совместимости на уровне исходных файлов с такими ассемблерами, но ничего для неё не генерирует.

.if abs-expression

Директива .if помечает начало секции кода, которая будет ассемблироваться только если аргумент abs-expression (который должен быть абсолютным выражением) не равен 0. Конец этой условно компилируемой секции должен быть помечен директивой .endif (см. её описание выше). Опционально вы можете поместить после блока .if блок альтернативы, начало которого помечается директивой .else (см. её описание выше).

Также поддерживаются следующие варианты .if:

.ifdef symbol

Ассемблирует свой блок, если был определен указанный символ symbol.

.ifndef symbol
.ifnotdef symbol

Ассемблирует свой блок, если указанный символ symbol не был определен. Оба этих варианта эквивалентны.

.include "file"

Предоставляет способ подключить файлы поддержки в определенном месте файла исходного кода. Код из файла file ассемблируется, как если бы его содержимое было вставлено в место, где появилась его директива .include. Когда вставляемый файл завершается, будет продолжено ассемблирование оригинального файла, где появилась директива .include. Вы можете управлять путями поиска файлов, используй ключ -I командной строки as (см. [7]). Вокруг имени файла file нужны двойные кавычки.

.int expressions

Принимает ноль или большее количество выражений expressions любых секций. Выражения отделяются друг от друга запятой. Для каждого выражения выдается число, которое во время выполнения (runtime) является значением этого выражения. Порядок байт и разрядность числа зависит от целевого процессора, для которого происходит ассемблирование.

.irp symbol, values...

Вычисляет последовательность операторов присваивания разных значений (values) символу (symbol). Последовательность операторов начинается с директивы .irp и завершается директивой .endr. Для каждого значения symbol устанавливается в значение value, и последовательность операторов ассемблируется. Если не перечислено ни одно из значений value, то последовательность операторов ассемблируется однократно, при этом symbol установится в пустую строку (null string). Чтобы обращаться к символу в последовательности операторов, используется \symbol.

Например, следующий код:

        .irp    param,1,2,3
        move    d\param,sp@-
        .endr

.. эквивалентен ассемблированию:

        move    d1,sp@-
        move    d2,sp@-
        move    d3,sp@-

.irpc symbol, values...

Вычисляет последовательность операторов, назначающих различные значения символу. Последовательность начинается с директивы .irpc, и завершается директивой .endr. Для каждого символа в value значение symbol установится в символ, и последовательность операторов ассемблируется. Если не указано ни одно value, то последовательность операторов ассемблируется однократно, при этом symbol установится в нулевую строку (null string). Чтобы обращаться к символу в последовательности операторов, используется \symbol.

Например, следующий код:

        .irpc    param,123
        move    d\param,sp@-
        .endr

.. эквивалентен ассемблированию:

        move    d1,sp@-
        move    d2,sp@-
        move    d3,sp@-

.lcomm symbol, length

Резервирует length (абсолютное выражение) байт для локального общего, обозначаемого symbol. Секция и значение символа соответствуют новому локальному общему. Адреса выделяются в секции bss, так что во время выполнения (run-time) соответствующие байты будут нулевые. Символ symbol не декларируется как глобальный (см. описание директив .global symbol, .globl symbol), так что обычно линковщик ld его не видит.

Некоторые целевые архитектуры позволяют с директивой .lcomm указывать третий аргумент. Этот аргумент задает желаемое выравнивание символа в секции bss.

Для архитектуры HPPA синтаксис .lcomm несколько отличается: 'symbol .lcomm, length', здесь указание symbol опционально.

.lflags

Ассемблер as принимает эту директиву для совместимости с другими ассемблерами, но игнорирует её.

.line line-number

Меняет логический номер строки. Параметр номера строки line-number должен быть абсолютным выражением. Следующая строка получает этот логический номер строки. Поэтому любые другие операторы не текущей строке (после символа разделения операторов) обозначаются логическим номером строки, равным line-number-1. Однажды эта директива больше не будет поддерживаться, она сейчас распознается только для совместимости с существующими версиями ассемблера.

Предупреждение: в конфигурации AMD29K ассемблера as эта директива недоступна; в этом контексте используйте синоним .ln.

Несмотря на то, что эта директива связана с форматом объектного кода a.out или b.out, она все еще распознается при генерации вывода в формат COFF, и обрабатывает '.line', как если бы для COFF была указана директива '.ln', если она находится вне пары .def/.endef.

Вместо этого внутри блока .def директива '.line' является одной из директив, используемых компиляторами для генерации вспомогательной символьной информации отладки.

.linkonce [type]

Пометит текущую секцию, так что линкер подключит для неё только одну копию. Это может использоваться для подключения той же самой секции в нескольких разных объектных файлах, но дает гарантию, что линкер в конечный выходной файл подключит обозначенную секцию только раз. Для каждого экземпляра этой секции нужно использовать .linkonce pseudo-op. Секции-дубликаты определяются на основе имени секции, так что уникальность имен секций должна соблюдаться.

Эта директива поддерживается только некоторыми форматами объектного файла; на момент написания этой документации as поддерживает только формат Portable Executable, используемый на Windows NT.

Аргумент type опциональный. Если он указан, то должен быть одной из следующих строк. Например:

.linkonce same_size

Не все типы могут поддерживаться всеми форматами объектных файлов.

discard

Молча отбрасывает дубликаты секций. Используется по умолчанию.

one_only

Предупреждает, что имеются дубликаты секций, но все еще оставляет только одну копию.

same_size

Предупреждает о том, что есть дубликаты другого размера.

same_contents

Предупреждает, что есть дубликаты с разным содержимым.

.ln line-number

Эта директива синоним директивы '.line'.

.mri val

Если параметр val не равен 0, то эта директива говорит ассемблеру as войти в режим MRI. Если val вычисляется как 0, то это говорит выйти из режима MRI. Это изменение влияет на код, который ассемблируется до следующей директивы .mri, или пока не будет достигнут конец файла. См. описание опции -M для режима совместимости MRI [8].

.list

Управляет (в сочетании с директивой .nolist), будут или нет генерироваться листинги ассемблирования. Эти две директивы поддерживают внутренний счетчик (значение которого изначально нулевое). Директива .list инкрементирует этот счетчик, и директива .nolist декрементирует его. Листинги ассемблера генерируются, когда счетчик больше нуля.

По умолчанию листинги запрещены. Когда вы их разрешили (опцией командной строки '-a', см. описание опций командной строки [7]), начальное значение счетчика листинга будет 1.

.long expressions

Директива .long то же самое, что и директива '.int', см. выше описание .int expressions.

.macro

Директивы .macro и .endm определяют тело макроса, который генерирует блок инструкций в коде ассемблера. Например, следующее определяет макрос sum, который поместит в память последовательность чисел:

        .macro  sum from=0, to=5
        .long   \from
        .if     \to-\from
        sum     "(\from+1)",\to
        .endif
        .endm

С таким определением макроса оператор 'SUM 0,5' эквивалентен следующему ассемблируемому коду:

        .long   0
        .long   1
        .long   2
        .long   3
        .long   4
        .long   5

.macro macname
.macro macname macargs ...

Начинает определение макроса с именем macname. Если ваш макрос требует для себя аргументы, то укажите их имена после имени макроса, отделяя друг от друга имена запятыми или пробелами. Вы можете предоставить значение по умолчанию для любого аргумента, если укажете после имени аргумента '=зн_умолч'. Например, все следующие определения макроса являются допустимыми:

.macro comm

Начало определения макроса comm, который не принимает аргументов.

.macro plus1 p, p1
.macro plus1 p p1

Любой из этих вариантов начала определяет макрос plus1, который принимает 2 аргумента; внутри тела макроса для доступа к значениям аргумента используйте '\p' или '\p1'.

.macro reserve_str p1=0 p2

Начинает определение макроса reserve_str, который принимает 2 аргумента. У первого аргумента задано значение по умолчанию, а для второго нет. После завершения определения вы можете вызывать этот макрос либо как 'reserve_str a,b' (обращаясь к значениям параметров a и b через '\p1' и '\p2'), или как 'reserve_str ,b' (здесь '\p1' получит значение по умолчанию, для нашего примера 0, и '\p2' получит значение b).

Когда вызывается макрос, можно указать указать значения аргумента либо по позиции, либо по ключевому слову. Например, 'sum 9,17' эквивалентно 'sum to=17, from=9'.

.endm

Помечает конец определения макроса.

.exitm

Ранний выход из текущего определения макроса.

\@

Ассемблер as поддерживает счетчик, сколько макросов было выполнено в этой псевдо-переменной; вы можете копировать это число в свой вывод, используя '\@', но только внутри тела макроса.

.nolist

Управляет (в сочетании с директивой .list) будут или нет генерироваться листинги ассемблирования. Эти две директивы поддерживают внутренний счетчик (значение которого изначально нулевое). Директива .list инкрементирует этот счетчик, и директива .nolist декрементирует его. Листинги ассемблера генерируются, когда счетчик больше нуля.

.octa bignums

Эта директива ожидает ноль или большее количество чисел bignums, отделенных друг от друга запятыми. Для каждого выдается 16-байтное целое число.

Термин "octa" произошел из контекста, в котором "слову" (word) соответствует 2 байта; отсюда octa-word определило восьмерку из 2 байт, т. е. 16 байт.

.org new-lc, fill

Перемещает счетчик текущего положения (адреса) текущей секции в новый адрес new-lc. Адрес new-lc здесь либо абсолютное выражение, либо выражение с той же секцией, что и текущая секция. Т. е. нельзя использовать .org для перескока на другую секцию: если new-lc оказывается на неправильной секции, то директива .org игнорируется. Для совместимости с предыдущими ассемблерами, если секция new-lc абсолютная, то as генерирует предупреждение и затем делает вид, что new-lc та же секция, что и текущая.

.org может только увеличивать счетчик позиции в секции, либо оставить его без изменения; нельзя использовать .org, чтобы отмотать счетчик обратно.

Из-за того, что as пытается выполнить сборку программ за один проход, new-lc не может быть неопределенным. Если вас реально бесит это ограничение, то разработчики надеются, что вы поделитесь с ними своей версией улучшенного ассемблера.

Имейте в виду, что отсчет .org указывается относительно начала секции, но не относительно начала субсекции. Это обеспечивает совместимость с ассемблерами других производителей.

Когда перемещается счетчик позиции (текущей субсекции), промежуточные байты заполняются значением параметра fill, который должен быть абсолютным выражением. Если запятая и fill опущены, то по умолчанию значение заполнения 0.

.p2align[w|l] abs-expr, fill, abs-expr

Дополняет счетчик позиции (в текущей субсекции) до определенной границы памяти (выравнивание). Первое выражение (которое должно быть абсолютным) это количество младших нулевых бит счетчика позиции после перемещения позиции. Например, '.p2align 3' увеличивает счетчик позиции до значения, которое нацело делится на 8 (2³). Если счетчик позиции уже и так нацело делится на 8, то его изменение для выравнивания не требуется.

Второе выражение (также абсолютное) задает значение заполнения, которое применяется для пропущенных при выравнивании байт. Этот параметр (и запятая перед ним) может быть опущен, тогда обычно применяются нулевые байты для заполнения. Однако на некоторых системах, если секция помечена как содержащая код, и параметр fill опущен, то пространство заполняется кодами инструкции no-op (нет операции).

Третье выражение также абсолютное, и также необязательное. Если оно присутствует, то задает максимальное количество байт, которое должно быть пропущено этой директивой выравнивания. Если выполнение выравнивания требует пропустить большее количество байт, чем указанный максимум, то выравнивание не производится вообще. Вы можете опустить значение заполнения fill (второй аргумент директивы), если просто укажете две запятые после первого параметра; это может быть полезным, если вы хотите заполнить пропущенные байты выравнивания инструкциями no-op.

Директивы .p2alignw и .p2alignl это варианты директивы .p2align. Директива .p2alignw рассматривает fill как значение двухбайтного слова (word, отсюда суффикс w). Директива .p2alignl рассматривает fill как значение четырехбайтного слова (longword, отсюда суффикс l). Например, .p2alignw 2,0x368d задает выравнивание так, чтобы полученный адрес нацело делился на 4. Если выравнивание приводит к пропуску 2 байт, то они будут заполнены значением 0x368d (точное размещение байт этого указанного слова зависит от endianness [5] целевого процессора). Если требуется пропустить 1 байт или 3 байта, то значение заполнения неопределенное.

.psize lines, columns

Используйте эту директиву для декларирования количества строк lines, и опционально количество столбцов columns для использования на каждой странице генерируемых листингов.

Если вы не используете .psize, то для листингов применяется значение по умолчанию счетчика строк 60. Вы можете опустить запятую и параметр columns, тогда по умолчанию для количества столбцов будет использоваться 200.

Ассемблер as генерирует код перевода формы (formfeed) всякий раз, когда превышается указанное количество строк (или когда перевод формы указывается напрямую с использованием .eject).

Если вы укажете в 0 для параметра lines, то коды перевода формы не генерируются, за исключенем тех, что явно указаны с помощью .eject.

.quad bignums

Директива .quad ожидает 0 или большее количество чисел bignums, отделенных друг от друга запятыми. Для каждого bignum директива генерирует 8-байтное целое число. Если bignum не помещается в 8 байт, то директива приведет к выводу предупреждения, и просто выдаст младшие 8 байт от bignum.

Термин "quad" произошел в контексте того, что слово (word) соответствует 2 байтам. Как следствие 4 слова quad-word соответствует 8 байтам.

.rept count

Повторит последовательность строк между директивой .rept и следующей директивой .endr. Количество повторений задается параметром count.

Например, ассемблирование:

        .rept   3
        .long   0
        .endr

.. эквивалентно:

        .long   0
        .long   0
        .long   0

.sbttl "subheading"

Эта директива указывает подзаголовок subheading (третья строка, сразу после строки заголовка) при генерации листингов ассемблера.

Эта директива влияет как на все последующие страницы, так и на текущую страницу, если появилась в пределах 10 строк от начала страницы.

.scl class

Установит для символа значение storage-class. Эта директива может использоваться только внутри пары .def/.endef. Класс хранилища class может пометить символ как static или external, или он может записать будущую символическую информацию для отладки.

Директива '.scl' главным образом связана с выводом в формате COFF; когда сконфигурирована генерация формата вывода b.out, ассемблер as примет эту директиву, но будет игнорировать её.

.section name

Директива .section используется для размещения последующего кода в секцию памяти с именем name.

Эта директива поддерживается только для целей (target), которые реально поддерживают произвольно именованные секции. Например на целях a.out это не поддерживается, даже со стандартным именем секции a.out.

Для целей COFF директива .section используется одним из следующих способов:

.section name[, "flags"]
.section name[, subsegment]

Если опциональный аргумент заключен в кавычки, то он берется как флаги для использования в этой секции. Каждый флаг представлен одиночным символом. Поддерживаются следующие флаги:

b секция bss (не инициализированные данные).
n секция не загружена.
w записываемая секция.
d секция данных. 
r секция только для чтения.
x секция с исполняемым кодом.

Если ни один флаг не указан, то флаги по умолчанию зависят от имени секции. Если имя секции не распознано, то по умолчанию применяется загружаемая и записываемая секция.

Если опциональный аргумент директивы .section не помещен в кавычки, то он берется как номер субсекции (см. "Sub-Sections" [2]).

Для целей ELF директива .section используется следующим образом:

.section name[, "flags"[, @type]]

Опциональный аргумент flags это строка, заключенная в кавычки, которая может содержать любую комбинацию следующих символов:

a секция может быть выделена.
w секция записываемая.
x секция содержит исполняемый код.

Опциональный аргумент type может содержать одну из следующих констант:

@progbits

Секция содержит данные.

@nobits

Секция не содержит данных (т. е. она только выделяет пространство в памяти).

Если аргумент flags не указан, то флаги по умолчанию зависят от имени секции. Если имя секции не распознано, то по умолчанию для секции не будет применен ни один из вышеуказанных флагов: секция не будет выделяться в памяти, её нельзя записать, она не содержит исполняемый код. Эта секция будет содержать данные.

Для целей ELF ассемблер поддерживает другой тип директивы .section для совместимости с ассемблером Solaris:

.section "name"[, flags...]

Обратите внимание, что здесь имя секции заключено в кавычки. Необязательный аргумент flags может содержать несколько отделенных друг от друга запятой флагов:

#alloc

Секция может быть выделена.

#write

Секция записываемая.

#execinstr

Секция содержит исполняемый код.

.set symbol, expression

Установит символ symbol в значение выражения expression. Это поменяет значение и тип символа так, чтобы он удовлетворял выражению expression. Если символ был помечен как external, то он остается помеченным (см. секцию "Symbol Attributes" документации [6]).

Вы можете применить .set для symbol несколько раз в одном и том же ассемблировании.

Если вы установите .set для глобального символа, то значение, сохраненное в объектном файле, будет последним сохраненным в нем значением.

Синтаксис директивы на архитектуре HPPA: 'symbol .set expression'.

.short expressions

Директива .short обычно означает то же самое, что и директива '.word', см. описание .word expressions.

Однако в некоторых конфигурациях .short и .word генерируют числа разной длины, см. далее раздел "Директивы, зависящие от целевого процессора".

.single flonums

Эта директива ассемблирует 0 или большее количество flonums, отделенных друг от друга запятыми. Она работает так же, как и директива .float. Точный вид формируемых чисел с плавающей точкой зависит от того, как сконфигурирован as, см. раздел "Директивы, зависящие от целевого процессора".

.size

Эта директива генерируется компиляторами для включения дополнительной отладочной информации в таблицу символов. Директива .size разрешена только внутри пар .def/.endef.

Директива .size имеет смысл только при генерации формата вывода COFF; когда генерируется b.out, директива принимается, но игнорируется.

.sleb128 expressions

Здесь sleb128 обозначает "signed little endian base 128", т. е. число little endian со знаком по основанию 128. Это используемое в формате символьной отладочной информации DWARF компактное, с переменной длиной, представление чисел. См. описание .uleb128 expressions.

.skip size, fill

Эта директива выдаст size байт, каждый со значением fill. Оба параметра size и fill являются абсолютными выражениями. Если запятая и параметр fill опущены, то подразумевается значение 0 для заполнения. Это работает так же, как директива '.space'.

.space size, fill

Эта директива выдает size байт, каждый из которых имеет значение fill. Оба параметра директивы это абсолютные выражения. Если fill (и запятая перед ним) опущено, то fill подразумевается равным 0. Это такое же поведение, как у '.skip'.

Предупреждение: .space полностью отличается по смыслу для целей (target) HPPA; в качестве замены используйте '.block', см. документацию "HP9000 Series 800 Assembly Language Reference Manual" (HP 92432-90001) для информации по назначению директивы .space (общую информацию см. во врезке "HPPA Assembler Directives").

На AMD 29K эта директива игнорируется; она принимается для совместимости с другими ассемблерами AMD 29K.

Предупреждение: на самых свежих версиях ассемблера GNU директива .space имеет эффект .block, см. врезку "AMD 29K".

.stabd
.stabn
.stabs

Существуют 3 директивы, начинающиеся на '.stab'. Все они генерируют символы (см. [6]) для использования символьных отладчиков. Символы не входят в таблицу хеша as: они никак не могут быть использованы кроме как для информации об исходном коде. Для директивы требуется заполнение до 5 полей:

string

Это имя символа, оно может содержать любой символ, кроме '\000', так что это более общее понятие, чем обычные имена символов. Некоторые отладчики используют это поле для кодирования произвольно сложных структур в имена символов.

type

Абсолютное выражение. Тип символа устанавливается в младшие 8 бит этого выражения. Разрешается применять любой шаблон бит, но линкер ld и отладчики входят избегают неправильных битовых последовательностей.

other

Абсолютное выражение. Из этого выражения используются младшие 8 бит для обозначения "другого" (other) атрибута символа.

desc

Абсолютное выражение. Из этого выражения используются младшие 16 бит для дескриптора символа.

value

Абсолютное выражение, которое становится значением символа.

Если обнаруживается предупреждение при чтении директив .stabd, .stabn или .stabs, то возможно символ уже был создан; вы получите в объектном файле наполовину сформированный символ. Так сделано для совместимости со старыми версиями ассемблера.

.stabd type, other, desc

"Имя" генерируемого символа не является пустой строкой. Для совместимости это нулевой указатель. Старые ассемблеры использовали нулевой указатель, чтобы не тратить место в объектных файлах с пустыми строками. Значение символа устанавливается на счетчик позиции с возможностью перемещения кода. Когда программа линкуется, значение этого символа будет адресом счетчика позиции при ассемблировании .stabd.

.stabn type, other, desc, value

Имя символа установится в пустую строку "".

.stabs string, type, other, desc, value

Указаны все 5 полей.

.string "str"

В объектный файл копируются символы строки str. Можно задать больше одной строки для копирования, отделенных друг от друга запятыми. Если для конкретной машины не указано нечто иное, то ассемблер пометит конец строки байтом 0. Можно использовать в строке любые esc-последовательности, см. "Strings" врезки "Символьные константы", а также описание синтаксиса строк [3].

.symver

Используйте директиву для привязки символов к определенным узлам версии в исходном файле. Это поддерживается только на ELF-платформах, и обычно используется, когда ассемблируются файлы для линковки в shared-библиотеку. Есть случаи, когда может быть смысл это использовать в объектных файлах для привязки в самом приложении, чтобы переопределить символ версии из shared-библиотеки.

Для целей ELF директива .symver используется следующим образом:

.symver name, name2@nodename

В этом случае имя символа name должно существовать, и быть определенным в ассемблируемом файле. Директива .versym эффективно создает псевдоним символа с именем name2@nodename, и на самом деле основная причина, по которой мы не пытаемся создать обычный псевдоним, заключается в том, что @ не разрешен в именах символов. Здесь часть name2 является реальным именем символа, с помощью которого на него могут быть внешние ссылки. Имя name просто является именем для удобства, чтобы можно было иметь несколько версий функции в одном исходном файле, и чтобы компилятор мог однозначно определить, какая упоминается версия функции. Часть nodename псевдонима должна быть именем узла, указанном в скрипте версии, предоставленным для линкера, когда выполняется сборка shared-библиотеки. Если вы пытаетесь переназначить versioned-символ из shared-библиотеки, то nodename должно соответствовать nodename символа, который вы пытаетесь переопределить.

.tag structname

Это директива, сгенерированная компиляторами для включения дополнительной отладочной информации в таблицу символов. Директива разрешена только внутри пар .def/.endef. Тэги используются для линковки определений структур в таблицу символов с экземплярами этих структур.

Директива '.tag' используется только при генерации вывода формата COFF; когда генерируется b.out, ассемблер принимает эту директиву, но игнорирует её.

.text subsection

Говорит ассемблеру as ассемблировать следующие операторы в конец нумерованной субсекции subsection (subsection абсолютное выражение). Если параметр subsection опущен, то используется субсекция 0.

.title "heading"

Используется heading в качестве заголовка (вторая строка, сразу после имени исходного файла и номера страницы) при генерации листингов ассемблирования.

Эта директива влияет как на последующие страницы, так и на текущую страницу, если директива оказалась в пределах 10 строк от начала страницы.

.type int

Эта директива, которая разрешена только внутри пар .def/.endef, запишет целое число int как тип атрибута элемента таблицы символов.

Директива '.type' связана только с форматом вывода COFF; когда as сконфигурирован для вывода в формат b.out, директива принимается, но игнорируется.

.val addr

Эта директива, которая разрешена только внутри пар .def/.endef, запишет адрес addr как значение атрибута в элемент таблицы символов.

Директива '.val' используется только для вывода формата COFF; когда as сконфигурирован для вывода в формат b.out, директива принимается, но игнорируется.

.uleb128 expressions

Здесь uleb128 означает "unsigned little endian base 128". Это компактное, с переменной длиной, представление чисел, используемое в символическом формате отладки DWARF. См. также выше описание .sleb128 expressions.

.word выражения

Эта директива ожидает ноль или большее количество выражений любой секции, отделенных друг от друга запятыми.

Размер выданного числа и его порядок байт зависят от целевой архитектуры и её порядка байт, для которой предназначена сборка.

Предупреждение: для поддержки компиляторов применяется специальная обработка.

Машины с 32-разрядным адресным пространством, но с менее чем 32-битной адресацией, требуют специальной обработки. Если интересующая вас машина выполняет 32-битную адресацию (или не требует этого, см. [4]), то можете игнорировать эту проблему.

Компилятор иногда делает странные вещи с директивой '.word', чтобы собрать код, который работает. Директивы в форме '.word sym1-sym2' часто выдаются компилятором как часть таблиц переходов (jump tables). Таким образом, когда as ассемблирует директиву в форме '.word sym1-sym2', и разность между sym1 и sym2 не укладывается в 16 бит, то as создает вторичную jump-таблицу, непосредственно перед следующей меткой. Этой вторичной jump-таблице  предшествует короткий jump на первый байт после вторичной таблицы. Этот короткий jump предотвращает управление потоком от случайного попадания в новую таблицу. Внутри таблицы содержится дальний jump на sym2. Оригинальное '.word' содержит sym1 минус адрес дальнего jump на sym2.

Если перед вторичной jump-таблицей было несколько директив '.word sym1-sym2', то все они корректируются. Если было '.word sym3-sym4', что также не укладывается в 16 бит, то дальний jump на sym4 включается во вторичную jump-таблицу, и директивы .word корректируются для содержания sym3 минус адрес дальнего jump на sym4. И так далее, для необходимого количества записей в исходной jump-таблице.

[Устаревшие директивы]

Когда-нибудь следующие директивы перестанут работать, пока что они оставлены для совместимости со старыми версиями ассемблеров.

.abort
.app-file
.line

[Директивы, зависящие от целевого процессора]

Наборы машинных инструкций, или системы команд процессора (как минимум по определению), отличаются для каждой машины (целевой платформы). Также может меняться представление чисел с плавающей запятой, и ассемблер as часто поддерживает несколько директив или опций командной строки, чтобы обеспечить совместимость с другими ассемблерами для определенной платформы. И наконец, некоторые версии as поддерживают специальные псевдоинструкции для оптимизации ветвления.

В этой главе обсуждаются многие из этих различий, хотя здесь не включены подробности по каждому набору машинных инструкций. Для получения подробной информации обращайтесь к документации производителя.

[Ссылки]

1. GNU Assembler Directives site:gnu.org.
2. GNU Assembler Sub-Sections site:gnu.org.
3. GNU Assembler Syntax Strings site:gnu.org.
4. Опции ARM компилятора GCC.
5. Порядок следования байт (endianness).
6. GNU Assembler Symbols site:gnu.org.
7. GNU Assembler Command-Line Options site:gnu.org.
8. GNU Assembler Assemble in MRI Compatibility Mode site:gnu.org.