Add a priority parameter for forcing SECTION FRAGMENTs to be sorted in a certain order using only code

[nitro2k01]

Currently SECTION FRAGMENTs are placed by the linker in the order of the input arguments. This can cause subtle breakage if a build tool like make reorders the files. My suggestion is a priority parameter which can be used to describe the order of SECTION FRAGMENTs using only the file contents, and not having to rely on forcing a certain parameter order by for example requiring alphabetically sorted file names and using sort to set the order explicitly.

The feature could have an integer argument, where a SECTION FRAGMENT with a lower argument will always be inserted before one with a higher argument.

The use case where this came up is code that starts in one SECTION FRAGMENT, runs to the end and then resumes in a different SECTION FRAGMENT in a different file. An example of how the proposed feature might work:

file1.asm:

SECTION FRAGMENT[0] "Stuff", ROMX 
DoSomeStuff::
    ; Stuff is being done

file2.asm:

SECTION FRAGMENT[10] "Stuff", ROMX 
    ; Do some cleanup
    ret

[dmitry-shechtman]

I second that. In my case, the same section is supposed to occur in

intro_init.asm
intro_copy.asm
intro_main.asm
intro_cleanup.asm

forcing the object targets to appear in that order in the Makefile.

Please allow for the integers to be non-consecutive.

[ISSOtm]

Here's how I envision this:

• A fragment whose priority is not specified defaults to 0.
• Priorities are signed.
• Ties are broken using link order (backwards compat, determinism).
• Non-consecutive priorities trigger a warning (default state is bikesheddable)

Example:

;; defines.inc (assume `--preinclude defines.inc`)

rsset -1
def PRIO_PROLOGUE rb 1
def PRIO_DEFAULT  rb 1
def PRIO_EPILOGUE rb 1

;; a.asm

SECTION FRAGMENT "Demonstration", ROM0 ; [2]
    xor a
    ldh [hNbCharsPrinted], a

;; b.asm

SECTION FRAGMENT[PRIO_EPILOGUE] "Demonstration", ROM0 ; [4]
    ret

SECTION FRAGMENT[PRIO_PROLOGUE] "Demonstration", ROM0 ; [1]
Label::

SECTION FRAGMENT[PRIO_DEFAULT] "Demonstration", ROM0 ; [3]
    xor a
    ldh [hMusicPlaying], a

rgblink a.o b.o would have the fragments concatenated in the commented order.

[dmitry-shechtman]

Looks good, only I wouldn't warn about non-consecutives. I was thinking old-times BASIC, where you'd do

10 PRINT "Hello, world"
20 GOTO 10

[ISSOtm]

A major difference is that fragments and their priorities are spread across multiple files, which begets mixups if used without a centralised definition.

[Rangi42]

default state is bikesheddable

I would paint this bikeshed off by default. Priorities sound to me like CSS z-indexes, where it's fine for there to be gaps because people might put "-999" or "10000" to mean "make this first/last", while leaving room for the middle parts to prioritize among themselves.

[nitro2k01]

• A fragment whose priority is not specified defaults to 0.
• Priorities are signed.
• Ties are broken using link order (backwards compat, determinism).

Agreed.

• Non-consecutive priorities trigger a warning (default state is bikesheddable)

Not sure what bikesheddable means here, but I would make the warning opt-in, not opt-out.

[Rangi42]

"Bikesheddable" meaning "a minor point which people can/will debate about anyway (but not a blocker for the overall feature)".

I agree it should be opt-in.

[AntonioND]

For more information about the word: http://phk.freebsd.dk/sagas/bikeshed/

[ISSOtm]

Another design would be to allow a fragment declare that it wants to be before some labels and/or after others; then, sections get sorted topologically according to such specifications.

The main benefit is not requiring some kind of global coordination of fragment priorities (“Is -9999 good enough?”), but instead stating what you want (“this must come after the Prologue and before the Epilogue... oh, and we must also run before Zonking!”).

Syntax proposals:

SECTION [Before,These,Labels]FRAGMENT[After,Those] ...
SECTION Before,These,Labels < FRAGMENT < After,Those ...
SECTION FRAGMENT > Before,These < After,Those ... ; Mathematical interpretation (“greater than”)
SECTION FRAGMENT < Before,These > After,Those ... ; Positional interpretation (“those are to the left”)
SECTION FRAGMENT[BEFORE Before,These AFTER After,Those] ... ; More keywords? (Possibly contextual, idk)

[Rangi42]

If we're going to add that sort of complex constraint declaration (presumably as part of using a full-blown constraint solver like Z3 to handle linker placement), I think it should go in the linker script, not the assembly file. Linker scripts still have simple syntax that has room to grow with before Label, after Label, etc declarations. But to me those syntax proposals all look very noisy, especially when you fill in the elided ... with everything else asm SECTION lines declare.