This is an archive of the discontinued LLVM Phabricator instance.

[docs] Add section 'Half-Precision Floating Point'
ClosedPublic

Authored by SjoerdMeijer on Jul 12 2017, 2:20 AM.

Details

Summary

This documents the differences and interactions between _Float16 and __fp16.

This is a companion change for the _Float16 type implementation in D33719.

Diff Detail

Repository
rL LLVM

Event Timeline

SjoerdMeijer created this revision.Jul 12 2017, 2:20 AM
SjoerdMeijer edited the summary of this revision. (Show Details)
simon_tatham added inline comments.Jul 12 2017, 2:43 AM
docs/LanguageExtensions.rst
448 ↗(On Diff #106154)

typo: artimethic -> arithmetic

454 ↗(On Diff #106154)

typo: egual -> equal

455 ↗(On Diff #106154)

Wording nit: "The difference with __fp16 is that ..." suggests that you're about to describe how __fp16 does things. Or at least it could be read as suggesting that.

Using "from" instead of "with" clarifies that you're saying how something is unlike fp16. I think I would also clarify by restating the type name in the subclause, along the lines of

The difference from ``__fp16`` is that arithmetic on ``_Float16`` is performed in half-precision, ...

Thanks for review! Feedback addressed.

simon_tatham added inline comments.Jul 12 2017, 4:00 AM
docs/LanguageExtensions.rst
457 ↗(On Diff #106167)

I think the use of "portable" here doesn't really give enough detail.

From an ARM-specific perspective, source code using _Float16 will be compiled into code that uses the hardware FP instructions for arithmetic on 16-bit FP values which were introduced in ARMv8.2, whereas __fp16 will be compiled into code that only uses the instructions to convert 16-bit to and from 32-bit, from a much earlier architecture revision. So from that perspective, using _Float16 will reduce portability, because it will make your code run (or at least run at full hardware-FP speed) on a smaller set of CPUs.

On the other hand, from a source language perspective, __fp16 is defined in an ARM-specific language extension, whereas _Float16 is defined by the C standards committee. So if your portability concern is between entire architectures, rather than between versions of the ARM architecture, then using _Float16 probably does help.

So I think it would probably be better to make some of this explicit – don't just say one or the other type is "more portable", but say something more specific about the circumstances in which each one can be expected to work.

Good points. I am thinking about how to write this down.
I am not yet sure that _Float16 can reduce portability. I think the behaviour will depend on FLT_EVAL_METHOD. I.e., if your architecture supports half-precision instructions, you would like to set FLT_EVAL_METHOD = 16, which would avoid evaluation in float and thus promotions/truncations. If your architecture does not support half-precision arithmetic, this will be FLT_EVAL_METHOD = 0 so that _Float16 is evaluated in float. So, from that point of view _Float16 can achieve the same things as '__fp16`, and it is more efficient when the hardware supports it and is indeed also more portable between entire architectures.

Addressed the comments about portability, and added a note that Float16 is available in both C and C++ mode.

simon_tatham added inline comments.Nov 2 2017, 2:50 AM
docs/LanguageExtensions.rst
462 ↗(On Diff #121003)

Sorry to nitpick a second time, but I think the phrase "entire architectures" is a bit strange here. I know it's the same phrase I actually *wrote* in my last review comment, but I was being a bit informal, and also explicitly contrasting with "versions of the Arm architecture" in the same sentence, to distinguish (say) "port between Arm and x86" from "port between ArmThis and ArmThat". Out of context it doesn't seem quite idiomatic or quite clear to me, so sorry to have accidentally suggested it!

How about something like this as alternative wording:

``__fp16`` is an ARM C-Language Extension (ACLE), whereas ``_Float16`` is defined by the C standards committee, so using ``_Float16`` will not prevent code from being ported to architectures other than Arm.

Many thanks for the reviews and suggestions! Comments addressed.

simon_tatham accepted this revision.Nov 2 2017, 3:06 AM

LGTM now, thanks! (But other reviewers may still want to comment.)

This revision is now accepted and ready to land.Nov 2 2017, 3:06 AM
This revision was automatically updated to reflect the committed changes.