hal.h

Go to the documentation of this file.

/*
  hal.h - HAL (Hardware Abstraction Layer) entry points structures and capabilities type
 
  Part of grblHAL
 
  Copyright (c) 2016-2025 Terje Io
 
  grblHAL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
 
  grblHAL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with grblHAL. If not, see <http://www.gnu.org/licenses/>.
*/
 
#ifndef _HAL_H_
#define _HAL_H_
 
#include <time.h>
 
#include "grbl.h"
#include "core_handlers.h"
#include "gcode.h"
#include "coolant_control.h"
#include "spindle_control.h"
#include "crossbar.h"
#include "stepper.h"
#include "nvs.h"
#include "probe.h"
#include "ioports.h"
#include "rgb.h"
#include "plugins.h"
 
#define HAL_VERSION 10
 
// Bitmap flags for driver capabilities, to be set by driver in driver_init() or plugins,
// flags may be cleared by plugins or the core to switch off capabilities.
typedef union {
    uint32_t value; 
    struct {
        uint32_t software_debounce         :1, 
                 step_pulse_delay          :1, 
                 limits_pull_up            :1, 
                 control_pull_up           :1, 
                 probe_pull_up             :1, 
                 amass_level               :2, // 0...3 Deprecated?
                 spindle_encoder           :1, 
                 spindle_sync              :1, 
                 sd_card                   :1,
                 littlefs                  :1,
                 bluetooth                 :1,
                 ethernet                  :1,
                 wifi                      :1,
                 spindle_pid               :1,
                 mpg_mode                  :1,
                 laser_ppi_mode            :1, 
                 atc                       :1, 
                 no_gcode_message_handling :1,
                 odometers                 :1,
                 pwm_spindle               :1,
                 probe_latch               :1,
                 toolsetter                :1, 
                 rtc                       :1,
                 rtc_set                   :1,
                 unassigned                :7;
    };
} driver_cap_t;
 
 
typedef bool (*driver_setup_ptr)(settings_t *settings);
 
typedef void (*driver_reset_ptr)(void);
 
typedef uint32_t (*get_free_mem_ptr)(void);
 
typedef void (*register_periph_pin_ptr)(const periph_pin_t *pin);
 
typedef void (*set_periph_pin_description_ptr)(const pin_function_t function, const pin_group_t group, const char *description);
 
typedef struct {
    register_periph_pin_ptr register_pin;               
    set_periph_pin_description_ptr set_pin_description; 
} periph_port_t;
 
typedef void (*pin_info_ptr)(xbar_t *pin, void *data);
 
typedef void (*enumerate_pins_ptr)(bool low_level, pin_info_ptr callback, void *data);
 
 
/*************
 *  Coolant  *
 *************/
 
typedef void (*coolant_set_state_ptr)(coolant_state_t state);
 
typedef coolant_state_t (*coolant_get_state_ptr)(void);
 
typedef struct {
    coolant_set_state_ptr set_state;    
    coolant_get_state_ptr get_state;    
} coolant_ptrs_t;
 
 
/********************
 *  Limit switches  *
 ********************/
 
typedef void (*limits_enable_ptr)(bool on, axes_signals_t homing_cycle);
 
typedef limit_signals_t (*limits_get_state_ptr)(void);
 
typedef void (*limit_interrupt_callback_ptr)(limit_signals_t state);
 
typedef struct {
    limits_enable_ptr enable;                           
    limits_get_state_ptr get_state;                     
    limit_interrupt_callback_ptr interrupt_callback;    
} limits_ptrs_t;
 
 
/************
 *  Homing  *
 ************/
 
typedef home_signals_t (*home_get_state_ptr)(void);
typedef float (*homing_get_feedrate_ptr)(axes_signals_t axes, homing_mode_t mode);
 
typedef struct {
    home_get_state_ptr get_state;                     
    homing_get_feedrate_ptr get_feedrate;
} homing_ptrs_t;
 
/*****************************
 *  Control signal switches  *
 *****************************/
 
typedef control_signals_t (*control_signals_get_state_ptr)(void);
 
typedef void (*control_signals_callback_ptr)(control_signals_t signals);
 
typedef struct {
    control_signals_get_state_ptr get_state;            
    control_signals_callback_ptr interrupt_callback;    
} control_signals_ptrs_t;
 
 
/**************
 *  Steppers  *
 **************/
 
typedef union {
    uint32_t value;
    struct {
        uint32_t id   : 8,
                 axis : 8;
    };
} motor_map_t;
 
typedef void (*motor_iterator_callback_ptr)(motor_map_t motor);
 
 
typedef void (*motor_iterator_ptr)(motor_iterator_callback_ptr callback);
 
 
typedef void (*stepper_wake_up_ptr)(void);
 
 
typedef void (*stepper_go_idle_ptr)(bool clear_signals);
 
typedef void (*stepper_enable_ptr)(axes_signals_t enable, bool hold);
 
typedef void (*stepper_disable_motors_ptr)(axes_signals_t axes, squaring_mode_t mode);
 
typedef void (*stepper_cycles_per_tick_ptr)(uint32_t cycles_per_tick);
 
typedef void (*stepper_pulse_start_ptr)(stepper_t *stepper);
 
typedef void (*stepper_output_step_ptr)(axes_signals_t step_outbits, axes_signals_t dir_outbits);
 
typedef axes_signals_t (*stepper_get_ganged_ptr)(bool auto_squared);
 
typedef void (*stepper_claim_motor_ptr)(uint_fast8_t axis_id, bool claim);
 
typedef stepper_status_t (*stepper_status_ptr)(bool reset);
 
typedef void (*stepper_interrupt_callback_ptr)(void);
 
typedef struct {
    stepper_wake_up_ptr wake_up;                        
    stepper_go_idle_ptr go_idle;                        
    stepper_enable_ptr enable;                          
    stepper_disable_motors_ptr disable_motors;          
    stepper_cycles_per_tick_ptr cycles_per_tick;        
    stepper_pulse_start_ptr pulse_start;                
    stepper_interrupt_callback_ptr interrupt_callback;  
    stepper_get_ganged_ptr get_ganged;                  
    stepper_claim_motor_ptr claim_motor;                
    stepper_output_step_ptr output_step;                
    motor_iterator_ptr motor_iterator;                  
    stepper_status_ptr status;                          
} stepper_ptrs_t;
 
 
/**************
 *  ms delay  *
 **************/
 
typedef void (*delay_callback_ptr)(void);
 
typedef struct {
   volatile uint32_t ms;
   delay_callback_ptr callback;
} delay_t;
 
 
/***********
 *  Probe  *
 ***********/
 
typedef probe_state_t (*probe_get_state_ptr)(void);
 
typedef void (*probe_configure_ptr)(bool is_probe_away, bool probing);
 
typedef void (*probe_connected_toggle_ptr)(void);
 
typedef struct {
    probe_configure_ptr configure;                  
    probe_get_state_ptr get_state;                  
    probe_connected_toggle_ptr connected_toggle;    
} probe_ptrs_t;
 
 
/*******************************
 *  Tool selection and change  *
 *******************************/
 
typedef void (*tool_select_ptr)(tool_data_t *tool, bool next);
 
typedef status_code_t (*tool_change_ptr)(parser_state_t *gc_state);
 
typedef struct {
    tool_select_ptr select; 
    tool_change_ptr change; 
} tool_ptrs_t;
 
 
/*******************
 *  Encoder input  *
 *******************/
 
typedef uint8_t (*encoder_get_n_encoders_ptr)(void);
 
typedef void (*encoder_on_event_ptr)(encoder_t *encoder, int32_t position);
 
typedef void (*encoder_reset_ptr)(uint_fast8_t id);
 
typedef struct {
    encoder_get_n_encoders_ptr get_n_encoders;  
    encoder_on_event_ptr on_event;              
    encoder_reset_ptr reset;                    
} encoder_ptrs_t;
 
typedef bool (*irq_claim_ptr)(irq_type_t irq, uint_fast8_t id, irq_callback_ptr callback);
 
/************
 *  Timers  *
 ************/
 
typedef void *hal_timer_t;  
 
typedef enum {
    Timer_16bit = 0,
    Timer_32bit,
    Timer_64bit
} timer_resolution_t;
 
typedef union {
    uint8_t value; 
    struct {
        uint8_t periodic :1, 
                up       :1, 
                comp1    :1, 
                comp2    :1; 
    };
} timer_cap_t;
 
typedef void (*timer_irq_handler_ptr)(void *context);
 
typedef struct {
    void *context;                          
    bool single_shot;                       
    timer_irq_handler_ptr timeout_callback; 
    uint32_t irq0;                          
    timer_irq_handler_ptr irq0_callback;    
    uint32_t irq1;                          
    timer_irq_handler_ptr irq1_callback;    
} timer_cfg_t;
 
typedef hal_timer_t (*timer_claim_ptr)(timer_cap_t cap, uint32_t timebase);
 
typedef bool (*timer_cfg_ptr)(hal_timer_t timer, timer_cfg_t *cfg);
 
typedef bool (*timer_start_ptr)(hal_timer_t timer, uint32_t period);
 
typedef bool (*timer_stop_ptr)(hal_timer_t timer);
 
typedef struct {
    timer_claim_ptr claim;
    timer_cfg_ptr configure;
    timer_start_ptr start;
    timer_stop_ptr stop;
} timer_ptrs_t;
 
/**************************
 *  RTC (Real Time Clock  *
 **************************/
 
typedef bool (*rtc_get_datetime_ptr)(struct tm *datetime);
 
typedef bool (*rtc_set_datetime_ptr)(struct tm *datetime);
 
typedef struct {
    rtc_get_datetime_ptr get_datetime;  
    rtc_set_datetime_ptr set_datetime;  
} rtc_ptrs_t;
 
 
 
typedef void (*pallet_shuttle_ptr)(void);
 
typedef struct {
    uint32_t version;               
    char *info;                     
    char *driver_version;           
    char *driver_options;           
    char *driver_url;               
    char *board;                    
    char *board_url;                
    uint32_t f_step_timer;          
    uint32_t f_mcu;                 
    uint32_t rx_buffer_size;        
    uint32_t max_step_rate;         
    uint8_t driver_axis_settings;   
 
    get_free_mem_ptr get_free_mem;
 
    driver_setup_ptr driver_setup;
 
    void (*delay_ms)(uint32_t ms, delay_callback_ptr callback);
 
    void (*set_bits_atomic)(volatile uint_fast16_t *value, uint_fast16_t bits);
 
    uint_fast16_t (*clear_bits_atomic)(volatile uint_fast16_t *value, uint_fast16_t v);
 
    uint_fast16_t (*set_value_atomic)(volatile uint_fast16_t *value, uint_fast16_t bits);
 
    void (*irq_enable)(void);
 
    void (*irq_disable)(void);
 
    irq_claim_ptr irq_claim;
 
    limits_ptrs_t limits;                   
    homing_ptrs_t homing;                   
    control_signals_ptrs_t control;         
    coolant_ptrs_t coolant;                 
    spindle_data_ptrs_t spindle_data;       
    stepper_ptrs_t stepper;                 
    io_stream_t stream;                     
    settings_changed_ptr settings_changed;  
    probe_ptrs_t probe;                     
    tool_ptrs_t tool;                       
    timer_ptrs_t timer;                     
    rtc_ptrs_t rtc;                         
    io_port_t port;                         
    rgb_ptr_t rgb0;                         
    rgb_ptr_t rgb1;                         
    periph_port_t periph_port;              
    driver_reset_ptr driver_reset;          
    nvs_io_t nvs;                           
    enumerate_pins_ptr enumerate_pins;      
    bool (*driver_release)(void);           
    uint32_t (*get_elapsed_ticks)(void);    
    uint64_t (*get_micros)(void);           
    pallet_shuttle_ptr pallet_shuttle;      
    void (*reboot)(void);                   
 
    encoder_ptrs_t encoder;                 
 
    bool (*get_position)(int32_t (*position)[N_AXIS]);
 
#ifdef DEBUGOUT
    void (*debug_out)(bool on);
    io_stream_t debug;                     
#endif
 
    bool (*stream_blocking_callback)(void);
 
    driver_cap_t driver_cap;                        
    control_signals_t signals_cap;                  
    control_signals_t signals_pullup_disable_cap;   
    limit_signals_t limits_cap;                     
    home_signals_t home_cap;                        
    coolant_state_t coolant_cap;                    
    home_signals_t motor_warning_cap;               
    home_signals_t motor_fault_cap;                 
} grbl_hal_t;
 
extern grbl_hal_t hal; 
 
extern bool driver_init (void);
 
#endif