Skip to content

hal: Break the HAL API - Move to 64-bit exclusively - #4565

Open
BsAtHome wants to merge 1 commit into
LinuxCNC:masterfrom
BsAtHome:hal64_break-hal-api-nodocs
Open

BsAtHome wants to merge 1 commit into
LinuxCNC:masterfrom
BsAtHome:hal64_break-hal-api-nodocs

Conversation

@BsAtHome

Copy link
Copy Markdown
Contributor

This is the long awaited HAL API break. The main update is that all 32-bit HAL pins/params/signals are gone and everything is now 64-bit with backing storage access completely opaque with the previous getter/setter update.

This PR does not include the docs. The PR is already large enough without having to go filter the docs while reviewing. The docs will follow in the next PR and is also quite a large patch set.

If you wonder about the HAL type name change... It was done to make a clean break. It is a clear sign that "from this point on we have a new HAL interface".

What changed:

  • HAL library:
    • HAL types HAL_{S32,U32} have been removed. All places where they were used have been updated to use the new abstract HAL_{SINT,UINT}.
    • Old HAL types HAL_{BIT,FLOAT,S64,U64} have been renamed to HAL_{BOOL,REAL,SINT,UINT}. Using any old types will result in a deprecation compiler warning.
    • Old access types like hal_data_u, hal_{bit,float,s32,u32,s64,u64}_t, real_t and ireal_t have been removed. There is no longer direct access to the underlying data. The new HAL types are hal_{bool,real,sint,uint,port}_t require you to use the getter/setter interface.
    • Pin and param direction types hal_pin_dir_t and hal_param_dir_t have been unified into hal_pdir_t. The code has been updated and using the old types will result in a deprecation warning. They must be removed at a (slightly) later stage.
    • The HAL_PORT interface has been changed to use the same interface as the other new HAL types to make the API as consistent as possible.
    • Old pin/param creation functions hal_pin_XXX_new() and hal_param_XXX_new() have been removed. These were already replaced by hal_pin_new_YYYY() and hal_param_new_YYYY()
    • Old parameter set functions hal_param_set*() and the value retrieval functions hal_get_{pin,param.signal}_value_by_name() have been removed. The query API has already replaced these in the previous updates to HAL.
    • The "use floating point" use_fp flag in functions and threads has been removed. It was already deprecated and fixed to true. The RTAPI has been updated as well.
    • The hal.h header now has a version define HAL_API_VERSION and is set to 1. It is now possible to track further changes in the API by inspecting this define to make user's code adapt more easily to future changes.
    • The tests have been updated to the new names so they all pass. It must be noted that tests for 32-bit value wrapping behaviour no longer exhibit that behaviour (specifically tests/halmodule/comp-set-get and tests/mux). If it is required to test wrapping, then the tests may be altered at a later stage.
  • HAL Components:
    • abs_s32 and abs_s64 have been folded into abs_sint
    • Old conv_XXXX_YYYY have all been removed and replaced by the new name versions {bool,real,sint,uint}.
    • demux_generic and mux_generic have been updated to handle any-to-any conversion for the new types. The pins that included the old names were also renamed.
    • scaled_s32_sums got renamed to scaled_sint_sums.
    • Component using letters to map types, like streams, will all map to the new HAL types. The old 64-bit identifiers 'l' and 'k' will automatically map to 's' and 'u' respectively for compatibility.
    • A large set of components already has their si32 and ui32 pins/params upgraded to sint and uint. However, there are still many components that need to be made 64-bit clean. This is a larger effort that will follow after integration of the PR. The [su]i32 types do create the correct [su]int typed pins and access through the getter/setter interface. The type marker is present as a reminder that they need updating. However, you cannot change the hal_[gs]et_[su]i32() getters/setters without properly inspecting the code where it is used. Every use needs to be inspected and traced to prevent intermediate variable truncation problems.
    • There are still instances where the s32 or u32 name is used in variables or pin/param/signal names. Not all can be changed easily while others may be replaced. Renaming must be a process that can be done after integrating these changes.
  • Utilities and consig samples:
    • halcmd and halrmt now issue a warning when the old HAL types are used. Printing/output data all uses the new types.
    • halshow will properly show the new types
    • All sample configs, where appropriate, were updated to use the new interfaces. Not all sample configs can be tested because some require actual hardware attached.
  • Python interfaces:
    • halmodule - The HAL types and pin/param direction have now IntEnums hal.Type.XXXX and hal.Dir.YYY. All code has been updated to use the new types.
    • halmodule - The use of the old HAL_XXX names will result in a deprecation warning. The old 32-bit versions will map to the new types.
    • GUI support library pyvcp now uses tags sint, uint, image_bool and image_uint. The old tags {s32,u32,image_u32,image_bit} are still recognized for compatibility. All in-tree xml files have been updated. The old names are still recognized but will emit a deprecation warning (only once for each type).
    • The pyui panelui now recognize {BOOL,REAL,SINT,UINT} as output type names. All in-tree examples have been updated. The old names are still recognized but will emit a deprecation warning (only once for each type).
  • and probably some details I missed in this already very long list...

The changes have been successfully tested on a RPi5+Mesa-7I96S+Modbus.

If you can, you should pull this branch (https://github.com/BsAtHome/linuxcnc/tree/hal64_break-hal-api-nodocs) from my repo and test on your machine/hardware and report back. Not that problems are expected, but testing this is necessary.

@BsAtHome

BsAtHome commented Sep 18, 2026

Copy link
Copy Markdown
Contributor Author

Forgot to note: Any hm2_modbus communication mbccb files need to be recompiled from the mbccs source with mesambccc. The file version was increased because of the HAL type changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant