Document ABI registers

[johnno1962]

Hi Apple,

A minor change to ABI manifesto to document register usage in the Swift ABI as it doesn’t seem to be documented elsewhere. If it is, just let me know!

Thanks,

John

[jckarter]

Thanks! This might be more discoverable if we put it in a doc under docs/ABI, maybe a new one just for the calling convention details.

[johnno1962]

NP. Having it close to discussion of the context/error regs seemed the most discoverable to me.

[jckarter]

Maybe that whole section of the document could be extracted into a new document(s) under the ABI directory? cc @rjmccall

[johnno1962]

Up to you, I confess I looked in the ABI directory when I was trying to puzzle this out.

[jckarter]

@rjmccall or @aschwaighofer should probably look over this for accuracy too.

[rjmccall]

"Register allocation" is an unfortunate name for this document. Maybe it could just be an appendix in CallingConvention.rst for all the target-specific CC choices?

That file needs some work, too. Among other things, it needs to be converted to Markdown.

[jckarter]

@rjmccall I think we should migrate it into subdocuments under the ABI subdirectory too. I think it'd be more discoverable, and easier for implementers to find the specifics they're looking for, there.

[rjmccall]

@rjmccall I think we should migrate it into subdocuments under the ABI subdirectory too. I think it'd be more discoverable, and easier for implementers to find the specifics they're looking for, there.

By "it" you mean CallingConvention.rst? I agree it should move into ABI/; I'm not sure how it would be useful to split up into different files, but if you have an idea, go ahead.

I suppose we should make a decision about whether target-specific information should be split into appendices of a bunch of different files or unified in a single file per target. The disadvantage of the former is that we're more likely to forget to include information about how a particular target implements a particular ABI feature; the disadvantage of the latter is that the different targets are likely to diverge in terms of the information they include in their documents and how they present it.

[jckarter]

By "it" you mean CallingConvention.rst? I agree it should move into ABI/; I'm not sure how it would be useful to split up into different files, but if you have an idea, go ahead.

Looking at it now, I think it's fine as a single document. I think I had CallingConvention.rst confused with the more catholic ABIStabilityManifesto doc.

[jckarter]

LGTM; any other comments @rjmccall @stephentyrone ?

[jckarter]

@swift-ci Please smoke test

[rjmccall]

This is fine; I'd still like to reach agreement about the point I raised above, but we don't need to pretend that this commit will be the last word.

[johnno1962]

Thanks everyone 👍