drivers: add generic upper-half driver for Field Oriented Control (FOC)

Documentation/components/drivers/character/foc.rst

@@ -0,0 +1,48 @@
+====================
+FOC Driver Interface
+====================
+
+Field Oriented Control (FOC) is a common technique to control
+either synchronous or asynchronous alternating current machines.
+The main goal of FOC is to control direct current (Id) and
+quadrature current (Iq) in powered device.
+
+The device on the kernel side is responsible for the following:
+
+#. update PWM duty cycles
+#. return ADC current samples
+#. synchronize user-space with PWM events
+
+The Nuttx FOC driver is split into two parts:
+
+#. An "upper half", generic driver that provides the common FOC
+   interface to application level code,
+#. A "lower half", platform-specific driver that implemets
+   the low-level logic to implement the FOC functionality
+
+Files supporting FOC can be found in the following locations:
+
+-  ``include/nuttx/motor/foc/foc.h``.
+   "Upper-half" FOC interface available for the user-space.
+-  ``include/nuttx/motor/foc/foc_lower.h``.
+   "Lower-half" FOC interface.
+-  ``drivers/motor/foc/foc_dev.c``.
+   The generic "upper half" FOC driver.
+
+The majority of the functionality available to the application
+is implemented in driver ioctl calls. Supported ioctl commands:
+
+- ``MTRIOC_START`` - Start the FOC device, arg: none.
+- ``MTRIOC_STOP`` - Stop the FOC device, arg: none.
+- ``MTRIOC_GET_STATE`` - Get the FOC device state,
+  arg: ``struct foc_state_s`` pointer.
+  This is a blocking operation that is used to synchronize the user space
+  application with ADC samples.
+- ``MTRIOC_CLEAR_FAULT`` - Clear the FOC device fault state,
+  arg: none.
+- ``MTRIOC_SET_PARAMS`` - Set the FOC device operation parameters,
+  arg: ``struct foc_params_s`` pointer.
+- ``MTRIOC_SET_CONFIG`` - Set the FOC device configuration,
+  arg: ``struct foc_cfg_s`` pointer.
+- ``MTRIOC_GET_INFO`` -  Get the FOC device info,
+  arg: ``struct foc_info_s`` pointer.

Documentation/components/drivers/character/index.rst

@@ -64,4 +64,5 @@ Character device drivers have these properties:
   watchdog.rst
   keypad.rst
   note.rst
+  foc.rst
 

drivers/Kconfig

@@ -130,3 +130,4 @@ source drivers/syslog/Kconfig
 source drivers/platform/Kconfig
 source drivers/rf/Kconfig
 source drivers/rc/Kconfig
+source drivers/motor/Kconfig

drivers/Makefile

@@ -29,6 +29,7 @@ include audio/Make.defs
 include bch/Make.defs
 include can/Make.defs
 include crypto/Make.defs
+include motor/Make.defs
 include i2c/Make.defs
 include i2s/Make.defs
 include input/Make.defs

drivers/motor/Kconfig

@@ -0,0 +1,14 @@
+#
+# For a description of the syntax of this configuration file,
+# see the file kconfig-language.txt in the NuttX tools repository.
+#
+
+menuconfig MOTOR
+	bool "Motor control drivers"
+	default n
+
+if MOTOR
+
+source "drivers/motor/foc/Kconfig"
+
+endif # MOTOR

drivers/motor/Make.defs

@@ -0,0 +1,35 @@
+############################################################################
+# drivers/motor/Make.defs
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+# Add FOC driver
+
+ifeq ($(CONFIG_MOTOR_FOC),y)
+include motor$(DELIM)foc$(DELIM)Make.defs
+endif
+
+# Include motor drivers in the build
+
+MOTOR_DEPPATH := --dep-path motor
+MOTOR_VPATH := :motor
+MOTOR_CFLAGS := ${shell $(INCDIR) "$(CC)" $(TOPDIR)$(DELIM)drivers$(DELIM)motr}
+
+DEPPATH += $(MOTOR_DEPPATH)
+VPATH += $(MOTOR_VPATH)
+CFLAGS += $(MOTOR_CFLAGS)

drivers/motor/foc/Kconfig

@@ -0,0 +1,31 @@
+menuconfig MOTOR_FOC
+  bool "FOC (Field Oriented Controller) driver support"
+  default n
+  ---help---
+    Enables building of the "upper-half" FOC driver.
+
+if MOTOR_FOC
+
+config MOTOR_FOC_INST
+       int "FOC instances"
+       default 1
+
+config MOTOR_FOC_PHASES
+       int "FOC phases number"
+       default 3
+
+config MOTOR_FOC_SHUNTS
+       int "FOC number of shunts"
+       range 1 3
+       default 3
+       ---help---
+         Number of shunts supported (or other types of current sensors).
+         Any current recontruction must be done on the lower-half side.
+
+config MOTOR_FOC_TRACE
+       bool "FOC trace support"
+       default n
+       ---help---
+         Enables FOC driver trace interface.
+
+endif #MOTOR_FOC

drivers/motor/foc/Make.defs

@@ -0,0 +1,29 @@
+############################################################################
+# drivers/motor/foc/Make.defs
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+# Include FOC driver into the build
+
+CSRCS += foc_dev.c
+
+# Include FOC driver build support
+
+DEPPATH += --dep-path motor$(DELIM)foc
+VPATH += :motor$(DELIM)foc
+CFLAGS += ${shell $(INCDIR) $(INCDIROPT) "$(CC)" $(TOPDIR)$(DELIM)drivers$(DELIM)motor$(DELIM)foc}

include/nuttx/fs/ioctl.h

@@ -86,6 +86,7 @@
 #define _RCIOCBASE      (0x2e00) /* Remote Control device ioctl commands */
 #define _HIMEMBASE      (0x2f00) /* Himem device ioctl commands*/
 #define _EFUSEBASE      (0x3000) /* Efuse device ioctl commands*/
+#define _MTRIOBASE      (0x3100) /* Motor device ioctl commands*/
 #define _WLIOCBASE      (0x8b00) /* Wireless modules ioctl network commands */
 
 /* boardctl() commands share the same number space */
@@ -541,6 +542,11 @@
 #define _EFUSEIOCVALID(c)   (_IOC_TYPE(c) == _EFUSEBASE)
 #define _EFUSEIOC(nr)       _IOC(_EFUSEBASE, nr)
 
+/* Motor drivers ************************************************************/
+
+#define _MTRIOCVALID(c)     (_IOC_TYPE(c) == _MTRIOBASE)
+#define _MTRIOC(nr)         _IOC(_MTRIOBASE, nr)
+
 /* Wireless driver network ioctl definitions ********************************/
 
 /* (see nuttx/include/wireless/wireless.h */

include/nuttx/motor/foc/foc.h

@@ -0,0 +1,158 @@
+/****************************************************************************
+ * include/nuttx/motor/foc/foc.h
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __INCLUDE_NUTTX_MOTOR_FOC_FOC_H
+#define __INCLUDE_NUTTX_MOTOR_FOC_FOC_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+#include <nuttx/compiler.h>
+
+#include <stdbool.h>
+#include <semaphore.h>
+
+#include <fixedmath.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+#define FOCDUTY_FROM_FLOAT(d)   (ftob16(d))
+#define FOCDUTY_FROM_FIXED16(d) (d)
+
+#define FOCDUTY_TO_FLOAT(d)     (b16tof(d))
+#define FOCDUTY_TO_FIXED16(d)   (d)
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/* FOC device fault code */
+
+enum foc_fault_e
+{
+  FOC_FAULT_NONE    = (0),      /* No fault */
+  FOC_FAULT_TIMEOUT = (1 << 1), /* Timeout fault */
+  FOC_FAULT_ARCH    = (1 << 2), /* Arch-specific fault */
+  FOC_FAULT_BOARD   = (1 << 3), /* Board-specific fault */
+};
+
+/* Phase current as signed 32-bit integer */
+
+typedef int32_t foc_current_t;
+
+/* Phase duty cycle as unsigned fixed16.
+ * We use range [0.0 to 1.0] so this gives us a 16-bit resolution.
+ */
+
+typedef ub16_t foc_duty_t;
+
+/* FOC device configuration */
+
+struct foc_cfg_s
+{
+  uint32_t pwm_freq;            /* FOC PWM frequency */
+  uint32_t notifier_freq;       /* FOC notifier frequency */
+};
+
+/* Output data from the FOC device */
+
+struct foc_state_s
+{
+  uint8_t       fault;                         /* Fault state */
+  foc_current_t curr[CONFIG_MOTOR_FOC_PHASES]; /* Phase current feedback */
+};
+
+/* Input data to the FOC device */
+
+struct foc_params_s
+{
+  foc_duty_t duty[CONFIG_MOTOR_FOC_PHASES]; /* PWM duty cycle for phases */
+};
+
+/* Hardware specific configuration */
+
+struct foc_hw_config_s
+{
+  uint32_t   pwm_dt_ns;   /* PWM dead-time in nano seconds */
+  foc_duty_t pwm_max;     /* Maximum PWM duty cycle */
+};
+
+/* FOC driver info */
+
+struct foc_info_s
+{
+  struct foc_hw_config_s hw_cfg; /* Hardware specific configuration */
+};
+
+/* FOC device upper-half */
+
+struct foc_lower_s;
+struct foc_typespec_s;
+struct foc_dev_s
+{
+  /* Fields managed by common upper-half FOC logic **************************/
+
+  uint8_t                    devno;      /* FOC device instance number */
+  uint8_t                    ocount;     /* The number of times the device
+                                          * has been opened
+                                          */
+  sem_t                      closesem;   /* Locks out new opens while close
+                                          * is in progress
+                                          */
+  sem_t                      statesem;   /* Notifier semaphore */
+
+  /* Fields provided by lower-half foc logic ********************************/
+
+  FAR struct foc_lower_s    *lower;      /* Reference to the FOC lower-half */
+
+  /* FOC device specific data ***********************************************/
+
+  struct foc_info_s          info;       /* Device info */
+  struct foc_cfg_s           cfg;        /* FOC common configuration */
+
+  /* FOC device input/output data *******************************************/
+
+  struct foc_state_s         state;      /* FOC device state */
+};
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+#ifdef __cplusplus
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+int foc_register(FAR const char *path, FAR struct foc_dev_s *dev);
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __INCLUDE_NUTTX_MOTOR_FOC_FOC_H */

include/nuttx/motor/foc/foc_lower.h

@@ -0,0 +1,144 @@
+/****************************************************************************
+ * include/nuttx/motor/foc/foc_lower.h
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __INCLUDE_NUTTX_MOTOR_FOC_FOC_LOWER_H
+#define __INCLUDE_NUTTX_MOTOR_FOC_FOC_LOWER_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <nuttx/motor/foc/foc.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* Only for kernel side */
+
+#ifndef __KERNEL__
+#  error
+#endif
+
+/* Helper macros */
+
+#define FOC_OPS_CONFIGURE(d, c)         (d)->lower->ops->configure(d, c)
+#define FOC_OPS_SETUP(d)                (d)->lower->ops->setup(d)
+#define FOC_OPS_SHUTDOWN(d)             (d)->lower->ops->shutdown(d)
+#define FOC_OPS_START(d, s)             (d)->lower->ops->start(d, s)
+#define FOC_OPS_DUTY(d, x)              (d)->lower->ops->pwm_duty_set(d, x)
+#define FOC_OPS_IOCTL(d, c, a)          (d)->lower->ops->ioctl(d, c, a)
+#define FOC_OPS_BIND(d, c)              (d)->lower->ops->bind(d, c)
+#define FOC_OPS_FAULT_CLEAR(d)          (d)->lower->ops->fault_clear(d)
+#ifdef CONFIG_MOTOR_FOC_TRACE
+#  define FOC_OPS_TRACE(d, t, s)        (d)->lower->ops->trace(d, t, s)
+#endif
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+#ifdef CONFIG_MOTOR_FOC_TRACE
+/* FOC trace type */
+
+enum foc_trace_type_e
+{
+  FOC_TRACE_NONE     = 0,       /* Not used */
+  FOC_TRACE_PARAMS   = 1,       /* In foc_params_set() */
+  FOC_TRACE_STATE    = 2,       /* In foc_state_get() */
+  FOC_TRACE_NOTIFIER = 3,       /* In foc_notifier() */
+  FOC_TRACE_LOWER    = 4        /* Reserved for lower-half code */
+};
+#endif
+
+/* Upper-half FOC callbacks  */
+
+struct foc_callbacks_s
+{
+  /* FOC notifier callback
+   *
+   * Description:
+   *   Deliver the phase current samples and wake up the thread waiting.
+   *   Must be called by lower-half logic at a frequency determined by
+   *   configuration (notifier_freq in foc_cfg_s).
+   */
+
+  CODE int (*notifier)(FAR struct foc_dev_s *dev,
+                       FAR foc_current_t *current);
+};
+
+/* Lower-half FOC operations */
+
+struct foc_lower_ops_s
+{
+  /* Lower-half configuration */
+
+  CODE int (*configure)(FAR struct foc_dev_s *dev,
+                        FAR struct foc_cfg_s *cfg);
+
+  /* Lower-half setup */
+
+  CODE int (*setup)(FAR struct foc_dev_s *dev);
+
+  /* Lower-half shutdwon */
+
+  CODE int (*shutdown)(FAR struct foc_dev_s *dev);
+
+  /* Set the PWM duty cycles */
+
+  CODE int (*pwm_duty_set)(FAR struct foc_dev_s *dev,
+                           FAR foc_duty_t *duty);
+
+  /* Lower-half start/stop */
+
+  CODE int (*start)(FAR struct foc_dev_s *dev, bool state);
+
+  /* Lower-half IOCTL */
+
+  CODE int (*ioctl)(FAR struct foc_dev_s *dev, int cmd,
+                    unsigned long arg);
+
+  /* Bind the upper-half driver with the lower-half logic */
+
+  CODE int (*bind)(FAR struct foc_dev_s *dev,
+                   FAR struct foc_callbacks_s *cb);
+
+  /* Lower-half fault clear */
+
+  CODE int (*fault_clear)(FAR struct foc_dev_s *dev);
+
+#ifdef CONFIG_MOTOR_FOC_TRACE
+  /* FOC trace */
+
+  CODE void (*trace)(FAR struct foc_dev_s *dev, int type, bool state);
+#endif
+};
+
+/* Lower-half FOC data - must be provided by lower-half implementation */
+
+struct foc_lower_s
+{
+  FAR struct foc_lower_ops_s *ops;    /* The FOC lower-half operations */
+  FAR void                   *data;   /* The FOC lower-half data */
+};
+
+#endif /* __INCLUDE_NUTTX_MOTOR_FOC_FOC_LOWER_H */

include/nuttx/motor/motor_ioctl.h

@@ -0,0 +1,49 @@
+/****************************************************************************
+ * include/nuttx/motor/motor_ioctl.h
+ * NuttX Motor-Related IOCTLs definitions
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __INCLUDE_NUTTX_MOTOR_MOTOR_IOCTL_H
+#define __INCLUDE_NUTTX_MOTOR_MOTOR_IOCTL_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+#include <nuttx/fs/ioctl.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/* All foc-related IOCTL commands must be defined in this header file
+ * in order to assure that every IOCTL command is unique and will not be
+ * aliased.
+ */
+
+#define MTRIOC_START          _MTRIOC(1)
+#define MTRIOC_STOP           _MTRIOC(2)
+#define MTRIOC_GET_STATE      _MTRIOC(3)
+#define MTRIOC_CLEAR_FAULT    _MTRIOC(4)
+#define MTRIOC_SET_PARAMS     _MTRIOC(5)
+#define MTRIOC_SET_CONFIG     _MTRIOC(6)
+#define MTRIOC_GET_INFO       _MTRIOC(7)
+
+#endif /* __INCLUDE_NUTTX_MOTOR_MOTOR_IOCTL_H */