The unsigned integer question

[grandixximo]

@rene-dev about the signed and unsigned integer use, these are what I found.

• encoder.N.counts => joint.N.jog-counts (s32 to s32): every MPG pendant configuration. In-tree alone: woodpecker mpg.hal, touchy, shuttle, xhc-hb04, and pico pendant.hal (rawcounts via ilowpass, s32 throughout). Motion's jog protocol is an exact per-cycle count delta (control.c:1066).

• iocontrol.0.tool-prep-number: axis_manualtoolchange.hal is pulled in by 50 in-tree inis, and smithy/924.hal nets it into classicladder s32 word logic on shipped commercial machines.

• Unsigned: hm2_modbus (in 2.9) maps raw device registers to pins, including 64-bit unsigned compounds (hal_pin_u64_newf, plus a u64 .offset tare doing modulo-2^64 subtraction). A totalizer register above 2^53 loses bits on a float pin; the range [2^63, 2^64) reads negative on s64. The pin is the user-facing register image, so "keep it driver-internal" does not apply.

• Bit patterns: hm2 raw.write-data and bitwise (u32 pins), plus lut5 (stepconf generates setp lut5.0.function 0x10000, a u32 param). On an integer pin, NaN and 2.5 are unrepresentable; today setp <int-pin> nan is rejected while setp <float-pin> nan succeeds, and (int32_t)NaN is 0x80000000 straight into an FPGA register. No driver checks isnan; the type is the guard.

[BsAtHome]

With respect to Modbus, any system that uses 64-bit (flag) registers cannot be read using floating point or important information will be lost. It may currently be rare to find these systems, but it is not unheard of in implementations that use read/write-in-depth instead of classic modbus register addressing.

Do we distinguish between the sets ℕ and ℤ? Normally, ℕ is a subset of ℤ. But in computers that is not the case with distinct ranges. If we are to abandon unsigned (ℕ), then we should also remove all use of unsigned types in the rest of the code. Arguing that the distinction is immaterial in one case but not the other would be inconsistent IMO.

[rene-dev]

hal and code are 2 different things. It is called hardware abstraction layer, not hardware access layer. I dont understand where the idea comes from that having hardware registers exposed as hal pins is useful for anything. It is the drivers job to abstract the hardware. in the case with encoders, it scales it to machine units, so it becomes useful. for a vfd, it converts rpm to whatever the vfd needs. linuxcnc does not even have a setting for scaling anything, it is always scaled in the driver.
anyone who has ever worked with machines using ethercat or modbus knows this.
Same applies for flag register. its the drivers job to extract the flags, and display them in a useful way.
52 bits is a lot more than the 32 we had for years.
a good example is this:
https://github.com/LinuxCNC/linuxcnc/blob/master/src/hal/components/eoffset_per_angle.comp#L9-L14
so they are making up a scale, and using the pin as a fixed point integer. This is mental.
in fact, I discovered that all of plasmac calculates height in fixed point integer, just because this pin is an integer. WHY.
this is another example:
https://github.com/LinuxCNC/linuxcnc/blob/master/src/hal/components/ilowpass.comp#L10-L14
because lowpassing an integer lacks resolution, you have to come up with a scale, and then convert back to float.
if those are gone, and they are both better of as a float, there are not many integer pins left, and my original question still remains unanswered:
is there any use for any integer pin in linuxcnc, that cant be a float?
if yes, can this pin be a signed integer, so we only have 2 types?

so far, lut5 is the only answer that came up.

I am talking about HAL, not about the code. Of course integer types are needed in the code.

[BsAtHome]

hal and code are 2 different things. It is called hardware abstraction layer, not hardware access layer. I dont understand where the idea comes from that having hardware registers exposed as hal pins is useful for anything.

Well, that is nice in theory, but unworkable in practice.

For example, the hostmot2 interfaces are interconnecting through HAL layering, where the "driver" as you call it is split between the protocol interface and the logic interface. For hm2_modbus this means you have a simple choice: reimplement the hardware/protocol interface provided by hm2_modbus for every Modbus device driver with all the problems that entails, or, interface your VFD (or other device) it at a higher level and let it connect to an abstracted protocol layer.

[rene-dev]

as far as I know pktuart, and hm2 are talking to each other using function calls, not hal pins, is that not the case?

[BsAtHome]

as far as I know pktuart, and hm2 are talking to each other using function calls, not hal pins, is that not the case?

This is not about pktuart, which is the transport layer (Layer 2; with hardware serial signalling at Layer 1). The protocol layer is modbus (Layer 3). The interconnect via HAL goes to the actual "device" drivers, which operate at Layers 4...7.

[grandixximo]

as far as I know pktuart, and hm2 are talking to each other using function calls, not hal pins, is that not the case?

hm2_modbus.c:2983-3025 creates one HAL pin per modbus data item from the compiled mbcc: bool, ui32, uint (u64), si32, sint (s64), real. The u64 flag-register case sits at line 3006 (hal_pin_new_uint).

So the Layer 3 to Layer 4+ interconnect Bertho describes is HAL pins by construction, and the device semantics live in the user's mbcc file, not in the driver. That is why hm2_modbus cannot scale or decompose registers itself: it is the protocol layer, and the meaning is defined downstream.

[grandixximo]

Conceding the two examples first: ilowpass and eoffset_per_angle are indeed scale-hack artifacts and would be better as float. I am not defending integer pins where a physical quantity is involved. If the list of integer pins were only those two, I would agree with you.

But the original question, "is there any integer pin that can't be a float", still has concrete cases on the table, so let me ask about those directly.

1. hm2_modbus exposes holding registers as pins, including u64 compounds. The component is a protocol bridge; it has no knowledge of the device on the other end, so there is no scaling it can apply. Bertho's point stands here: the alternative is every VFD driver reimplementing the modbus interface itself. What should a u64 register in the range [2^63, 2^64) read as on a float pin? On a signed pin it reads negative. Is either acceptable for a register image?

2. lut5.0.function is a bit pattern; stepconf generates setp lut5.0.function 0x10000. If this pin becomes float, what should setp lut5.0.function 2.5 do, and what should setp lut5.0.function nan do? Today the type rejects both. If the type no longer rejects them, which component checks isnan before the value lands in an FPGA register?

3. Same question for hm2 raw.write-data, a u32 bit pattern written verbatim to hardware. What does scaling mean for a bitmask?

4. iocontrol tool-prep-number feeds classicladder s32 word logic in smithy/924.hal on shipped commercial machines, and axis_manualtoolchange.hal is pulled in by 50 in-tree inis. If this becomes float, who re-verifies those configurations, and what is gained that justifies that?

5. On the consistency question Bertho raised and I haven't seen answered: if the ℕ/ℤ distinction is immaterial at the pin level, why is it material in the code? A u32 register image and a u32 C variable describe the same hardware fact. What changes at the HAL boundary?

My actual position is narrower than "keep everything": physical quantities should be float, counts and register images should stay integer, and bit patterns should stay unsigned. That gives us float + signed + unsigned, which is what we have. The two-type proposal (float + s64) answers cases 1 through 3 with either lost information or silent truncation, so I am asking: what does it buy that justifies that?

[andypugh]

I know that we are trying to get away from parameters, but some of the examples above are parameter-like rather than pin-like.
lut5 should just reject non-integer definitions. LUT5,N,function isn't net-able.
The same is sort-of true for the hm2_raw pins. These would not, typically, be part of a HAL net. They may occasionally see use with a sequence of "setp" commands in a HAL file, but really exist for debug and bleeding-edge hack purposes when the drivers haven't caught up with new hm2 modules.

To implement LUT5 with a float input pin, you would simply cast to int before indexing into the int. If that isn't what the user intended, then that's on them for specifying a stupid function value.

[grandixximo]

Fair points on both. lut5.0.function is a param, and raw.write-data is a debug escape hatch; neither carries the pin argument on its own, so I will drop them.

The case that remains is hm2_modbus. Its pins are not params and not debug hooks: they are the component's primary interface, created one per compiled mbcc item precisely so users can net register contents into their own logic (hm2_modbus.c:2983-3025, u64 at line 3006). The component is a protocol bridge; the device semantics live in the user's mbcc file, so there is nothing in the driver that could scale or decompose the register on the way out.

For a u64 holding register, float loses bits above 2^53 and s64 reads [2^63, 2^64) as negative. That is the entire remaining question for the two-type proposal: what should that pin be?

[grandixximo]

Let me concede the sharp version first: nothing on the table is bit-lossy on s64. A u64 register in [2^63, 2^64) keeps every bit on a signed pin; only the display and comparisons change. What unsigned carries is semantics and a guard, not information. So the question is whether that guard is worth a type.

Precedent says yes. Classic Siemens S7 had no unsigned integers for decades and TIA added USINT..ULINT for the S7-1200/1500; Allen-Bradley Logix went the same way. Not for arithmetic: CIP, PROFINET, OPC UA and CoE object dictionaries are unsigned by definition, and a signed-only controller pushes the "if x < 0 then x + 65536" idiom onto every user at that boundary. LinuxCNC has three such boundaries in tree already (hm2_modbus, sserial streams, lcec generic). Dropping uint now walks the same path those vendors reversed.

The busiest of those boundaries is CiA 402. lcec exposes 0x6041 statusword and 0x6040 controlword as u32 pins, and the drive state machine lives in a separate component, cia402.comp, which declares pin in unsigned statusword and pin out unsigned controlword, extracts every status bit by shift and mask, and assembles the control word by OR. Every EtherCAT servo config nets those two words per axis. Two independently maintained components agree on a bit-pattern contract across a HAL net; that is the register image on a pin, in the mainstream path, with an integer type as the only thing standing between a NaN and the drive enable.

The API break has quietly built the untyped-word model: every integer pin is one 64-bit word, and si32/ui32 are accessor views on it. Only hal_link has not caught up; it still demands exact type equality, so a ui32 pin cannot be netted to a uint pin holding identical bytes. That is the mismatch users actually hit and the reason 29 conv components exist.

Proposal, the middle ground:

1. Net types: bit, sint, uint, real, port. The si32/ui32 markers retire component by component, as already on Bertho's list.
2. Netting sint to uint is allowed with a warning. Storage is identical, so it is lossless; the warning flags the probable mistake. This is how TwinCAT links PLC variables to PDOs: match by size, warn on a type mismatch instead of refusing. Class mismatch (int to real, bit to int) stays an error.
3. setp on a uint pin keeps rejecting negative, fractional and nan values. That is the guard a float-only HAL loses, and it applies to netted values too, since no consumer can receive a nan through an integer signal.
4. Signal semantics need no new mechanism. The signal already is the storage, one 64-bit word whatever the type; the type tag on it only serves hal_link, the display tools (halcmd, halshow, halmeter, halscope, the Python and GUI bindings) and sets, and each component already interprets the word through its own accessor on the pin pointer. The one rule to add: a mixed net keeps the tag of the first pin netted, so every display tool and sets follow it. A sint writer on a uint reader shows two's complement. Documented once, next to the warning text.
5. conv shrinks from 29 components to 5 (bit and real conversions), the same count as the float+s64 proposal.

Modbus then needs a policy, not a type. hm2_modbus already implements it: scaled items go out as real through an s64 cast (hm2_modbus.c:1991), raw register images go out as uint, and the mbcc chooses per item. Stated as policy: physical quantities are real, register images are uint. Two gaps to close so the raw path is usable: bitslice and bitwise take ui32 today, so a 64-bit flag register has no in-tree consumer, and the display tools should offer hex for uint pins (halcmd, halshow, halmeter at least), which removes the "reads negative" complaint at the root.

What this costs relative to two numeric types: one extra case in every generic switch (mux_generic, sampler, streamer, halmodule, halcmd and the GUI widget libraries). That is the whole remaining price, and I think the guard plus the three protocol bridges are worth it.

[BsAtHome]

Meant to write: hal_{pin,param}_new_[su]i32() are aliases...

[grandixximo]

@BsAtHome, first two concessions. My opening claim that a ui32 pin cannot be netted to a uint pin, and the count of 29 converters, were from master; in your patch HAL_S32 is HAL_SINT and conv is already 11. And on si32/ui32 you are right: they stay as creation aliases and accessor shortcuts, they are just not net types.

Including bool: agreed. It also fixes a latent bug: hal_set_bool() writes _u while hal_get_bool() reads _b, which on a big-endian machine is the high byte, so every bool reads false. Debian has not built LinuxCNC on a big-endian architecture since bookworm (s390x), so nothing breaks today, but the double negation over the full word removes the trap.

On the signal type I would keep today's rule: the type comes from newsig or the first pin of net and never changes afterwards. No majority, no following. Every added pin is already compared with the signal type, in preflight_net_cmd() and in hal_link(); that comparison does not need a writer and works for I/O pins. The change is only that a mismatch within the integer class (bool, sint, uint) becomes a warning instead of an error.

NaN in the converters: agreed, detection needs a replacement. The detection itself can be free. Writing the clamp tests inverted, if(!(val <= MAX)) and if(!(val >= MIN)), sends NaN into the first branch with the same compare count (checked with gcc 14 on x86), so it comes out as MAX with out_of_range set. Whether MAX is the right replacement or the previous output should be held through a transient is the open question; holding costs one extra test.

That leaves two open points: the NaN replacement value, and @rene-dev's FPU flag check.

[BsAtHome]

With respect to NaN we might do something like this, including infinity handling:

component conv_real_sint "Convert a value from real to sint";
pin in   real in;
pin out  sint out;
pin out  bool out_of_range;
pin in   sint replace_nan = 0 "NaN replacement";
pin in   sint replace_inf_positive = RTAPI_SINT_MAX "Positive infinity replacement";
pin in   sint replace_inf_negative = RTAPI_SINT_MIN "Negative infinity replacement";
param rw bool clamp_;
;;
#include <rtapi_stdint.h>
rtapi_real val = in;
int inf;
if(isnan(val)) {
    out_set(replace_nan);
} else if(0 != (inf = isinf(val))) {
    out_set(inf < 0 ? replace_inf_negative : replace_inf_positive);
} else {
    if(clamp_) {
        if(val >= (rtapi_real)RTAPI_SINT_MAX) {
            out_set(RTAPI_SINT_MAX);
            out_of_range_set(1);
        } else if(val <= (rtapi_real)RTAPI_SINT_MIN) {
            out_set(RTAPI_SINT_MIN);
            out_of_range_set(1);
        } else {
            out_set((rtapi_sint)val);
            out_of_range_set(0);
        }
    } else {
        if(val != (rtapi_real)out_set((rtapi_sint)val)) {
            out_of_range_set(1);
        }
    }
}

Partially taken from the current code. It should be noted that out_of_range never gets reset when clamp_ is false. This makes it potentially less useful. OTOH, it may otherwise just "blink" once in a while. Not sure whether it is useful at all in a non-clamping context.

Replacements are pins because you may want to drive them dynamically.

[grandixximo]

Replacements as pins is a good call, and it gives hold-last for free: net out back into replace_nan and a transient NaN holds the previous value.

I built your sketch against the #4565 tree and ran it under halrun next to a fixed version. Four things came up:

1. isinf() does not portably give the sign. C only promises nonzero. glibc returns -1 for -inf, so the sketch works in uspace, but on kernel builds rtapi_math.h maps isinf to __builtin_isinf(), which returns 1 for both, so -inf gets the positive replacement. signbit() is available in both paths.
2. The NaN and inf branches never set out_of_range, so the pin stays quiet exactly when the input is bad.
3. With clamp_ off, (rtapi_sint)val outside [-2^63, 2^63) is undefined, not a wrap: 9.3e18 comes out as SINT_MIN on x86, and -fsanitize=float-cast-overflow flags it. There is no wrap to offer for real to int, so it always has to saturate, and clamp_ has no job left in the real to int converters.
4. Without clamp, val != out also flags every fractional input (1.5 gives TRUE), and the flag latches. I made it follow the input each cycle; whoever wants a latch can add one.

It also needs #include <rtapi_math.h> for isnan()/isinf().

component conv_real_sint "Convert a value from real to sint";
pin in   real in;
pin out  sint out;
pin out  bool out_of_range "TRUE while 'in' is NaN, infinite or outside the range of sint";
pin in   sint replace_nan = 0 "NaN replacement";
pin in   sint replace_inf_positive = RTAPI_SINT_MAX "Positive infinity replacement";
pin in   sint replace_inf_negative = RTAPI_SINT_MIN "Negative infinity replacement";
option period no;
function _;
license "GPL";
;;
#include <rtapi_stdint.h>
#include <rtapi_math.h>
FUNCTION(_) {
    rtapi_real val = in;
    if(isnan(val)) {
        out_set(replace_nan);
        out_of_range_set(1);
    } else if(isinf(val)) {
        // isinf() does not return the sign in kernel builds (__builtin_isinf)
        out_set(signbit(val) ? replace_inf_negative : replace_inf_positive);
        out_of_range_set(1);
    } else if(val >= (rtapi_real)RTAPI_SINT_MAX || val < (rtapi_real)RTAPI_SINT_MIN) {
        // (rtapi_real)RTAPI_SINT_MAX rounds up to 2^63, itself out of range.
        // Converting outside [-2^63, 2^63) is undefined in C, so saturate.
        out_set(val > 0 ? RTAPI_SINT_MAX : RTAPI_SINT_MIN);
        out_of_range_set(1);
    } else {
        out_set((rtapi_sint)val);
        out_of_range_set(0);
    }
}

halrun results, one input per cycle in this order (oor = out_of_range):

in	sketch, clamp_ off	sketch, clamp_ on	fixed
nan	0, FALSE	0, FALSE	0, TRUE
inf	SINT_MAX, FALSE	SINT_MAX, FALSE	SINT_MAX, TRUE
-inf	SINT_MIN, FALSE	SINT_MIN, FALSE	SINT_MIN, TRUE
1.5	1, TRUE	1, FALSE	1, FALSE
9.3e18	SINT_MIN, TRUE	SINT_MAX, TRUE	SINT_MAX, TRUE
-9.3e18	SINT_MIN, TRUE	SINT_MIN, TRUE	SINT_MIN, TRUE
-2^63	SINT_MIN, TRUE	SINT_MIN, TRUE	SINT_MIN, FALSE
5	5, TRUE	5, FALSE	5, FALSE

(-inf shows correctly for the sketch here because this is a uspace build.) The fixed logic runs clean under -fsanitize=float-cast-overflow on the edge values, including 2^63 - 1024 (in range) and -2^63 - 2048 (out). conv_real_uint has the same shape with the range test val >= (rtapi_real)RTAPI_UINT_MAX || val <= -1.0 (-0.5 truncates to 0 and is in range) and 0 as the default negative infinity replacement; I checked that logic the same way.

[BsAtHome]

That removes the clamp input. That is probably a good thing, but also will need .hal file updates.

For the uint case, val < 0.0 maps to zero with out-of-range set. There is no negative in unsigned values.

Seen the complexities in these real-to-X routines, they should not be generated anymore. All conversion routines should become static components.