ADCLP USER GUIDE

---

REVISION HISTORY

Revision No.	Description	Date
1.0	Initial release	09/06/2024
1.1	Improve hardware function and FAQ description	04/14/2025
1.2	added description of channel mode	06/13/2025

---

1. OVERVIEW

The Successive Approximation ADC uses a feedback comparison circuit structure. The implementation method is briefly summarized as follows: take a digital quantity and add it to the DAC to get a corresponding output analog voltage. Compare this analog voltage with the input analog voltage signal. If the two are not equal, adjust the digital quantity until the two analog voltages are equal. The final digital quantity is the desired conversion result.

2. KEYWORD DESCRIPTION

• ADCLP

  Analog-to-digital converter Low Precision, low-precision (10-bit) analog-to-digital converter.

• ADCMP

  Analog-to-digital converter Medium Precision, medium-precision (12bit) analog-to-digital converter.

• Upper/lower bound

  ADCLP can set the upper and lower limits of the external input voltage digital quantity, and an interrupt will be triggered if it exceeds the range.

• Reference voltage

  The reference voltage used for analog-to-digital conversion calculations, which is also the maximum range. If the reference voltage is set to 1.8v, when the external input voltage is >=1.8v, the digital value reaches the maximum value of 1023.

3. FUNCTION DESCRIPTION

3.1. Hardware Function Description

• SAR ADCLP has a total of 5 channels that can support analog-to-digital conversion of external input voltage.

• The sampling accuracy is 10 bits, so the acquired register value range is 0~0x3ff.

• Supports switching of two-level reference voltage (i.e. full scale), which are 1.8V and 1.0V respectively.

• Sampling frequency = 12Mhz / 104 = 115384hz (equivalent to a sampling interval of 8667ns per point on the hardware).

• The channel mode can be selected from 1 channel / 4 channel / 8 channel / 9 channel. Different modes determine the time interval for data update. If 1 channel mode is selected, it means that the hardware only enables 1 channel, and the time interval for ADC data update is 8667ns. If 4 channel mode is selected, the time interval for ADC data update is (8667ns * 4)

• Supports threshold setting of external input voltage. When the voltage exceeds the threshold range, an interrupt will be triggered. The response time of the hardware interrupt (excluding software processing time) will be affected by the time interval of ADC data update. If the 1-channel mode is selected, the response time of the hardware interrupt is at least greater than 8667ns. If the 4-channel mode is selected, the response time of the hardware interrupt is at least greater than (8667ns * 4)

3.2. Calculation instructions

The main function of SAR ADCLP is to convert analog signals into corresponding digital signals, that is, it can convert the input voltage into digital quantities and store them in registers, and calculate the input voltage through the formula.

Calculation formula: voltage = (register value / full scale) * reference voltage.

That is, if the value read is 0x1D2, the voltage is 0x1D2/0x3FF *1.8 = about 0.82v.

4. HARDWARE CONNECTION INTRODUCTION

As shown in the figure below, the external voltage can be connected to the pins PM_SAR_GPIO0~PM_SAR_GPIO4.

Figure 4-1: Adclp-1

5. UBOOT USAGE INTRODUCTION

5.1. Uboot Config Configuration

Check Kconfig to see that supporting ADCLP requires configuring CONFIG_SSTAR_ADCLP, CONFIG_ADC and CONFIG_CMD_ADC. To enable CONFIG_CMD_ADC, you need to configure DM_REGULATOR first.

1. Configure CONFIG_SSTAR_ADCLP

   

   Figure 5-1: Adclp-2

2. Configure CONFIG_ADC

   

   Figure 5-2: Adclp-3

3. Configure DM_REGULATOR

   

   Figure 5-3: Adclp-5

4. Configure CONFIG_CMD_ADC

   

   Figure 5-4: Adclp-4

5.2. DTS Configuration

The DTS configuration of SAR ADCLP only needs to configure the following information in chipname.dtsi:

adclp: adclp {
    compatible = "sstar,adclp";
    reg = <0x1F002800 0x200>;
    chan-num = <5>;
    ref-voltage = <1800>;
    status = "okay";
};

SAR ADCLP DTS configuration description:

Attribute	Description	Setting Value	Remark
compatible	Match the driver to register the driver	"sstar,adclp"	Modification prohibited
reg	Set the register bank address	<0x1F002800 0x200>	Modification prohibited
chan-num	Set the number of channels supported	5	Modification prohibited
ref-voltage	Set the reference voltage level	In mv, 1800 and 1000 can be selected	Can be modified as needed
status	Select whether to enable the driver	"okay" or "disable"	Can be modified as needed

5.3. Uboot cmd Parameter Description and Use Case

In command lines, input adc:

Figure 5-5: Adclp-6

(1) adc list -> check whether sar adclp is bound.

Figure 5-6: Adclp-7

(2) adc info adclp -> view the number of channels and data precision supported by sar adclp.

As shown below, the number of channels currently supported is 5 (note that the mask is 0x1f), and the maximum data value is 0x3ff.

Figure 5-7: Adclp-8

(3) adc single adclp [channel] -> view the data of a specific channel.

As shown in the figure below, the value of channel 0 is 605.

According to the formula: voltage = (data / 0x3ff) * reference voltage.

At this time, the voltage is 605 / 1023 * 1.8 V = 1.065V.

Figure 5-8: Adclp-9

(4) adc scan adclp [channel mask] -> view the data of multiple channels.

adc scan adclp: view the data of all channels.

Figure 5-9: Adclp-10

adc scan adclp 0x3: -> view the data of channel 0 and channel 1.

Figure 5-10: Adclp-11

6. KERNEL USAGE INTRODUCTION

6.1. Kernel Config Configuration

SAR ADCLP associated driver module Config:

• CONFIG_IIO

SAR ADCLP driver enable requires the following configuration:

Device Drivers --->

    [*] Sstar SoC platform drivers --->

        <*> Sstar ADCLP driver

6.2. DTS Configuration

The DTS configuration of SAR ADCLP only needs to configure the following information in chipname.dtsi:

adclp0: adclp0@1f002800 {
    compatible = "sstar,adclp";
    interrupt-parent = <&sstar_pm_main_intc>;
    interrupts = <INT_PMSLEEP_IRQ_SAR_KP>;
    reg = <0x0 0x1F002800 0x0 0x200>;
    clocks = <&CLK_sar>;
    interrupt-enable;
    channel = <0>;
    ref-voltage = <1800>;
    upper-bound = <0x3FF>;
    lower-bound = <0>;
    status = "ok";
};

Attribute	Description	Setting Value	Remark
compatible	Match the driver to register the driver	"sstar,adclp"	Modification prohibited
interrupt-parent	Bind the interrupt controller	&sstar_pm_main_intc	Modification prohibited
interrupts	Bind the interrupt number	INT_PMSLEEP_IRQ_SAR_KP	Modification prohibited
reg	Set the register bank address	0x1F002800	Modification prohibited
clocks	Set the clock source	&CLK_sar	No modification required
interrupt-enable	Enable the interrupt	bool type, the comment means disable	Can be modified as needed
channel	Set the channel	0~4	No modification required
ref-voltage	Set the reference voltage level	In mv, 1800 and 1000 can be selected	Can be modified as needed
upper-bound	Set the upper threshold voltage	0~0x3FF, enable interrupt	Can be modified as needed
lower-bound	Set the lower threshold voltage	0~0x3FF, enable interrupt	Can be modified as needed
status	Whether to enable the driver	"ok" or "disable"	Can be modified as needed

The number of channels enabled by adclp determines the channel mode of the hardware:

• When only one channel is enabled, the hardware uses 1 channel mode

• When multiple channels are enabled, the maximum value of the dts channel attribute is < 4, and the hardware uses 4 channel mode

• When multiple channels are enabled, the maximum value of the dts channel attribute is >= 4, and the hardware uses 8 channel mode

6.3. Padmux Configuration

SAR-ADCLP does not require padmux configuration, and the PIN pins on the schematic diagram will be configured as ADC sampling function by default.

6.4. Module Usage Introduction

6.4.1 SYSFS Interface Description

1. Enter SAR ADCLP sampling channel Channel 0

   cd /sys/class/sstar/adclp0/
   

2. Set the threshold of SAR ADCLP0 (sampling will not be affected if the threshold is not set)

   echo 800 400 > /sys/class/sstar/adclp0/threshold
   

3. Enable SAR ADCLP0

   echo 1 > enable
   

4. Get the digital quantity after SAR ADCLP0 sampling

   cat /sys/class/sstar/adclp0/value
   

6.4.2 Ioctl Interface Description

The header File<drv_adclp.h> is located in the kernel/driver/sstar/sar directory.

• IOCTL_ADCLP_SET_BOUND

  Set the sampling voltage threshold.

• IOCTL_ADCLP_READ_VALUE

  Get the digital quantity after voltage conversion.

• IOCTL_ADCLP_VDD_TYPE

  Get the VDD digital value of a special channel according to the VDD type

enum adclp_vdd_type
{
    ADCLP_VDD_CPU = 0,
    ADCLP_VDD_DLA,
    ADCLP_VDD_MIU,
    ADCLP_VDD_CORE,
    ADCLP_VDD_NODIE,
    ADCLP_VSS,
};

struct adclp_bound
{
    unsigned short upper_bound;
    unsigned short lower_bound;
};

#define ADCLP_IOC_MAXNR 2

#define ADCLP_IOC_MAGIC        'a'
#define IOCTL_ADCLP_SET_BOUND  _IO(ADCLP_IOC_MAGIC, 0)
#define IOCTL_ADCLP_READ_VALUE _IO(ADCLP_IOC_MAGIC, 1)
#define IOCTL_ADCLP_VDD_TYPE   _IO(ADCLP_IOC_MAGIC, 2)

6.5. Sample Code

6.5.1 Ioctl

The source code is located in kernel/driver/sstar/sar/ut/ut_adclp.c.

#include <fcntl.h>
#include <stdio.h>
#include <errno.h>
#include <signal.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/ioctl.h>
#include <sys/types.h>
#include <drv_adclp.h>

void sample_warn(int num)
{
    printf("adclp data exceeding the threshold\n");
}

int main(int argc, char **argv)
{
    int                fd;
    char               cmd;
    int                flags;
    unsigned short     value;
    unsigned int       channel;
    char               path[64];
    struct adclp_bound adclp_bd;

    if (argc == 2)
    {
        channel = atoi(argv[1]);
    }
    else if (argc == 4)
    {
        channel              = atoi(argv[1]);
        adclp_bd.upper_bound = atoi(argv[2]);
        adclp_bd.lower_bound = atoi(argv[3]);
    }
    else
    {
        printf("format: ut_adclp [channel] <upper> <lower>\n");
        return -1;
    }

    snprintf(path, sizeof(path), "/dev/adclp%u", channel);
    fd = open((const char *)(char *)path, O_RDWR);
    if (fd < 0)
    {
        printf("open device fail\n");
        return -1;
    }

    if (argc == 4)
    {
        ioctl(fd, IOCTL_ADCLP_SET_BOUND, &adclp_bd);
    }

    signal(SIGIO, sample_warn);

    fcntl(fd, F_SETOWN, getpid());
    flags = fcntl(fd, F_GETFL);
    fcntl(fd, F_SETFL, flags | FASYNC);

    while (1)
    {
        cmd = getchar();
        if (cmd == 'q' || cmd == 'Q')
        {
            break;
        }

        ioctl(fd, IOCTL_ADCLP_READ_VALUE, &value);
        printf("adclp%u data[%hu]\n", channel, value);
    }

    close(fd);

    return 0;
}

6.5.2 Kernel Mode

#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/moduleparam.h>
#include <linux/platform_device.h>
#include <linux/of.h>
#include <drv_adclp.h>

static adclp_cb_t cb_t[4];

int adclp_get_data2(u8 channel)
{
    u16 data;

    sstar_adclp_get_data(channel, &data);
    printk("%s adclp test chan[%d], data[%hu]\n", __func__, channel, data);

    return 0;
}

int adclp_get_data1(u8 channel)
{
    u16 data;

    sstar_adclp_get_data(channel, &data);
    printk("%s adclp test chan[%d], data[%hu]\n", __func__, channel, data);

    return 0;
}

static int __init adclp_test_init(void)
{
    int ret;

    cb_t[0] = adclp_get_data1;
    ret = sstar_adclp_register_callback(0, cb_t[0]);
    if (ret)
    {
        printk("adclp ch0-0 register callback fail\n");
        return ret;
    }

    cb_t[1] = adclp_get_data2;
    ret = sstar_adclp_register_callback(0, cb_t[1]);
    if (ret)
    {
        printk("adclp ch0-1 register callback fail\n");
        return ret;
    }

    cb_t[2] = adclp_get_data1;
    ret = sstar_adclp_register_callback(1, cb_t[2]);
    if (ret)
    {
        printk("adclp ch1-0 register callback fail\n");
        return ret;
    }

    cb_t[3] = adclp_get_data2;
    ret = sstar_adclp_register_callback(1, cb_t[3]);
    if (ret)
    {
        printk("adclp ch1-1 register callback fail\n");
        return ret;
    }

    ret = sstar_adclp_set_bound(0, 800, 600);
    if (ret)
    {
        printk("adclp ch0 set bound fail\n");
        return ret;
    }

    ret = sstar_adclp_set_bound(1, 1000, 600);
    if (ret)
    {
        printk("adclp ch1 set bound fail\n");
        return ret;
    }

    sstar_adclp_enable(0, 1);
    sstar_adclp_enable(1, 1);

    return 0;
}

static void __exit adclp_test_exit(void)
{
    sstar_adclp_enable(0, 0);
    sstar_adclp_enable(1, 0);

    sstar_adclp_unregister_callback(0, cb_t[0]);
    sstar_adclp_unregister_callback(0, cb_t[1]);
    sstar_adclp_unregister_callback(1, cb_t[2]);
    sstar_adclp_unregister_callback(1, cb_t[3]);
}

module_init(adclp_test_init);
module_exit(adclp_test_exit);

7. API Reference

The API can refer to header file <drv_adclp.h> located in the kernel/driver/sstar/sar directory.

enum adclp_vdd_type
{
    ADCLP_VDD_CPU = 0,
    ADCLP_VDD_DLA,
    ADCLP_VDD_MIU,
    ADCLP_VDD_CORE,
    ADCLP_VDD_NODIE,
    ADCLP_VSS,
};

typedef int (*adclp_cb_t)(u8 channel);

//This function module provides the following kernel state interfaces
int sstar_adclp_enable(u8 channel, u8 enable);
int sstar_adclp_get_data(u8 channel, u16 *data);
int sstar_adclp_set_bound(u8 channel, u16 max, u16 min);
int sstar_adclp_vdd_data(u8 channel, u16 *data, enum adclp_vdd_type type);
int sstar_adclp_register_callback(u8 channel, adclp_cb_t cb_t);
int sstar_adclp_unregister_callback(u8 channel, adclp_cb_t cb_t);

sstar_adclp_enable

• Purpose

  Enable sampling function of the specified channel.

• Syntax

  int sstar_adclp_enable(u8 channel, u8 enable);
  

• Parameter

  Parameter Name	Description
  channel	Sampling channel
  enable	Whether to enable

• Return Value

  Return Value	Description
  0	Success
  EINVAL	Channel not supported

sstar_adclp_get_data

• Purpose

  Get the external input voltage digital quantity of the specified channel.

• Syntax

  int sstar_adclp_get_data(u8 channel, u16 *data)
  

• Parameter

  Parameter Name	Description
  channel	Sampling channel
  data	Pointer address to obtain sampling data

• Return Value

  Return Value	Description
  0	Success
  EINVAL	Channel not supported

sstar_adclp_set_bound

• Purpose

  Set the threshold of the specified channel.

• Syntax

  int sstar_adclp_set_bound(u8 channel, u16 max, u16 min)
  

• Parameter

  Parameter Name	Description
  channel	Sampling channel
  max	Upper threshold
  min	Lower threshold

• Return Value

  Return Value	Description
  0	Success
  EINVAL	Channel not supported

sstar_adclp_vdd_data

• Purpose

Get the adc code of a special channel without external input voltage. The adc code value depends on the type passed in by adclp_vdd_type.

• Syntax

  int drv_adclp_vdd_data(u8 channel, u16 *data, enum adclp_vdd_type type)
  

• Parameter

  Parameter Name	Description
  channel	Here it is specified as 8
  data	Voltage digital quantity
  type	Enumeration，choose VDD_CORE,VDD_CPU,VDD_DLA, etc

• Return value

  Return value	Description
  0	Success
  EINVAL	Channel not supported

sstar_adclp_register_callback

• Purpose

  Register the callback function of the specified channel (supports registering multiple callback functions for the same channel). When the sampling result exceeds the threshold, the callback function can be used to perform corresponding processing.

• Syntax

  int sstar_adclp_register_callback(u8 channel, adclp_cb_t cb_t)
  

• Parameter

  Parameter Name	Description
  channel	Sampling channel
  cb_t	Function pointer

• Return Value

  Return Value	Description
  0	Register successfully
  EINVAL	Register failed

sstar_adclp_unregister_callback

• Purpose

  Release the callback function of the specified channel and the memory applied during registration.

• Syntax

  int sstar_adclp_unregister_callback(u8 channel, adclp_cb_t cb_t)
  

• Parameter

  Parameter Name	Description
  channel	Sampling channel
  cb_t	Function pointer

• Return Value

  Return Value	Description
  0	Unregister successfully
  EINVAL	Unregister failed

8. FAQ

Q1：SAR ADCLP Interface Does Not Exist

1. Check if the status of the DTS ADCLP node is ok

2. Check if the kernel config is configured, see [6.1. Kernel Config Configuration]

Q2: The external input voltage changes, but the SAR ADCLP sampling data does not change

1. When the PIN is in GPIO MODE, the sampling data will not change. You can read the register value to determine whether the PIN is switched to GPIO MODE:

   0x14 0x11 BIT0-BIT5:
   Each BIT of BIT0~BIT5 corresponds to a channel. When value=0, the PIN pin of the channel is in GPIO MODE. When value=1, the PIN pin of the channel is in ADC MODE. For example, when BIT0=0, channel 0 is in GPIO MODE. When BIT1=1, channel 1 is in ADC MODE.
   
   0x14 0x11 BIT8-BIT13:
   Each BIT of BIT8~BIT13 corresponds to a channel. The prerequisite is that the PIN pin is in GPIO MODE. When value=0, the PIN pin is switched to output. When value=1, the PIN pin is switched to input.
   
   0x14 0x12 BIT0-BIT5:
   Each BIT of BIT0~BIT5 corresponds to a channel. The prerequisite is that the PIN pin is in GPIO MODE and is set to ouput. When value=0, the PIN pin of the channel is switched to a low level. When value=1, the PIN pin of the channel is switched to a high level.
   
   For example: riu_r 0x14 0x11
   Return value: 0x3F3F -> All channels are in ADC MODE
   Return value: 0x3E3E -> Channel 0 is in GPIO MODE, and the rest of the channels are in ADC MODE
   Return value: 0x0000 -> All channels are in GPIO MODE and switched to output
   

2. When the PIN pin register is set to non-GPIO MODE, the sampled data still does not change. You can set the PIN pin to GPIO MODE and perform an output high/low test. If the PIN pin level cannot be pulled up or down, it can be judged as a hardware problem.

Q3: The first or first few sampling data have a large deviation from the actual input voltage

This problem is most likely related to the sampling timing. You can use GPIO as a trigger source to obtain the voltage status of the component at each sampling.

As shown in the figure below, before triggering ADC sampling, GPIO switches from high level to low level. The ADC sampling timing is just in the process of voltage decline, not when the voltage is stable. Therefore, it is judged as sampling abnormality. At this time, it is necessary to wait until the component is stable before sampling.