AHI Functions and Explanations for DIO (GPIO)

DIO (GPIO)

Some of the AHI functions related to DIO (GPIO) are implemented for source-level compatibility.

Overview

The pin assignment architecture differs from that of TWELITE BLUE/RED. Here, pins used in TWELITE BLUE/RED are labeled as DIO0..19/DO0..1/ADC0…3, while the pin names for the semiconductor used in TWELITE GOLD are labeled as PIO0..21. For details about the pins, refer to the semiconductor datasheet for each module.

• Some pins on the module are not mapped one-to-one:
  • PIO0 is shared with DIO11 and DO0.
  • PIO14 is shared with DIO8 and ADC1.
• Regarding DIO interrupts, there are the following differences:
  • DIO0..19 supported independent interrupts, but since this feature does not exist here, the GINT (group interrupt) feature is used to achieve similar behavior. (Another feature called PINT supports independent interrupts but only for up to four ports, so it is not used in this library.)
  • Hardware interrupt detection is only available on both edges; internal interrupts occur on either edge.
    • While running (not in sleep mode), whether to call the AHI interrupt handler is determined by the pin state after the interrupt occurs, so the fact that detection is on both edges is not apparent.
    • The edge for wake-up from sleep cannot be specified.

Pin Assignment

AHIcmpt_Dio.cpp - Definitions and Constants

Definitions

#define BOARD_GPIO_PORT_MAX_PIN_COUNT 22 // Number of pins
#define BOARD_GPIO_PIN_TABLE_SIZE 24     // Rounded up to a multiple of 4 for 22 pins

g_twenet_ioport_remap_by_PIOn[]

const uint8 g_twenet_ioport_remap_by_PIOn[BOARD_GPIO_PIN_TABLE_SIZE];

(For internal library use) Table for converting PIO numbers to DIO numbers.

• 0x80: SPIMISO pin
• 0x90: ADC1 pin (analog only)
• 0xFF: Unused / undefined

g_twenet_ioport_remap_by_AHIn[]

const uint8 g_twenet_ioport_remap_by_AHIn[BOARD_GPIO_PIN_TABLE_SIZE];

(For internal library use) Table for referencing PIO numbers from AHI numbers.

AHIcmpt_Dio.cpp - Definitions

Variables

uint32 G_TWENET_IOPORT_OUTPUT_BM() = 0;　　　　　　 // DIO bitmap for output ports
uint32 G_TWENET_IOPORT_INT_ENABLED_BM() = 0;      // DIO bitmap for interrupt-enabled ports
uint32 G_TWENET_IOPORT_INT_RISING_BM() = 0;       // DIO bitmap for rising-edge interrupt-enabled ports
uint32 G_TWENET_IOPORT_INT_FALLING_BM() = 0;      // DIO bitmap for falling-edge interrupt-enabled ports
volatile uint32 G_TWENET_IOPORT_INT_STATUS() = 0; // DIO bitmap recording wake-up pins when woken by DIO interrupt
uint32 G_TWENET_IOPORT_WAKE_STATUS() = 0;         // DIO bitmap storing I/O interrupt sources at wake-up

• Each DIO bitmap corresponds bit n to DIOn (e.g., for DIO0 and DIO3, use (1UL << 0) | (1UL << 3)).

check_pio(), get_pio(), get_dio()

static inline bool check_pio(uint8 u8pio);
static inline uint8 get_pio(const uint8 u8dio);
static inline uint8 get_dio(const uint8 u8pio);

• check_pio(): An inline function that checks whether the specified PIO number is valid and not already used by another peripheral.
• get_pio(): Returns the PIO number corresponding to the specified DIO number. Returns 0xff if the assignment is invalid.
• get_dio(): Returns the DIO number corresponding to the specified PIO number. Returns 0xff if the assignment is invalid.

s_gpio_int_handler()

static void s_gpio_int_handler(uint32 bm_pio, uint32 bm_pio_changed, void* p_data);

Interrupt handler function internally called when a DIO interrupt occurs.

• If there is a pin change, interrupt information is sent via AppQAPI using __twenet_vAppQApiPostHwIntT().

AHIcmpt_Dio.cpp - AHI Function Definitions

vAHI_DioSetDirection()

void   vAHI_DioSetDirection(
    uint32      u32Inputs,
    uint32      u32Outputs);

Configures the input/output direction of ports.

• In principle, ports are set to input state at initialization, but strictly speaking, the initial state is defined by the BOARD_InitPins() initialization in the TWENETmcu library’s pinmux.c.

vAHI_DioSetOutput()

void   vAHI_DioSetOutput( // u32On:HIGH, u32Off::LOW
    uint32      u32On,
    uint32      u32Off);

Changes the output state of ports. u32On is the DIO bitmap for pins to set HIGH, and u32Off is the DIO bitmap for pins to set LOW.

• When multiple pins are specified, the changes are not simultaneous.
  • This is because, in the internal implementation, each pin is set individually within a loop.

vAHI_DioSetPullup()

void   vAHI_DioSetPullup(
    uint32      u32On,
    uint32      u32Off);

Configures the pull-up state.

• In principle, the default is pull-up enabled, but strictly speaking, the initial state is defined by the BOARD_InitPins() initialization in the TWENETmcu library’s pinmux.c.

u32AHI_DioReadInput()

uint32 u32AHI_DioReadInput(void);

Retrieves the state of all ports at once.

• The return value is a bitmap representing the state of all ports: bits set to 1 indicate HIGH level, and bits set to 0 indicate LOW level.
• The values for non-existent DIO numbers or ports used by peripherals are undefined.

vAHI_DioWakeEnable()

void   vAHI_DioWakeEnable(
    uint32      u32Enable,
    uint32      u32Disable);

Starts DIO interrupts. u32Enable specifies the DIO bitmap for adding interrupt handling, and u32Disable specifies the DIO bitmap for removing interrupt handling. Additionally, you must specify the interrupt edge for the enabled pins using vAHI_DioWakeEdge().

• The behavior is undefined when specifying pins that are not configured as inputs (e.g., output pins or pins assigned to other peripheral functions).

vAHI_DioWakeEdge()

void   vAHI_DioWakeEdge(
    uint32      u32Rising,
    uint32      u32Falling);

Configures the interrupt pins. This call sets both rising and falling edges for the specified pins at once. Note that you cannot add or remove edges individually.

Although the function name contains “Wake,” it configures both runtime interrupt handling and wake-up-from-sleep behavior.

• If the same pin is specified for both u32Rising and u32Falling, interrupts occur on both edges due to the design principle. (However, since this is not a valid AHI setting, it is outside the scope of operation verification.)
• During interrupt operation, vAHI_DioWakeEnable() is called internally for reconfiguration.
• The behavior is undefined when specifying pins that are not configured as inputs (e.g., output pins or pins assigned to other peripheral functions).
• For wake-up from sleep, the interrupt edge is always set to both edges.

u32AHI_DioWakeStatus()

uint32 u32AHI_DioWakeStatus(void);

Returns the bitmap of pins that triggered the wake-up during a DIO interrupt.

• Internally, it returns the value of __twenet_ioport_int_status at the time of the call. After the call, the value is set to 0.

bAHI_DoEnableOutputs()

static inline bool_t bAHI_DoEnableOutputs(bool_t bEnableDO) {
	return bAHI_DoEnableOutputsEx_MW(bEnableDO, bEnableDO);
}

Configures the DO0 and DO1 pins as output.

• Both DO0 and DO1 are configured as output.
• To configure only one pin, call bAHI_DoEnableOutputsEx_MW().
  • DO1 (PIO5) is assigned to the pin used to determine transition to program mode (ISP_ENT) at startup, so it requires attention in hardware design. Unless there is a special reason, it is recommended to use a different pin.
• DO0 (PIO0) is also assigned to DIO11, so if both are used, code adjustments (excluding control of one side) are required.

vAHI_DoSetDataOut()

void vAHI_DoSetDataOut(
    uint8       u8On,
    uint8       u8Off);

Configures output settings for DO0 (PIO0) and DO1 (PIO1).

• DO0 is specified by bit0 (0x1), and DO1 is specified by bit1 (0x2) in the bitmap.
• Setting a bit in u8On sets the output to HIGH level, while setting it in u8Off sets the output to LOW level.

vAHI_DoSetPullup()

 void vAHI_DoSetPullup(
    uint8       u8On,
    uint8       u8Off);

Does nothing.

AHIcmpt_Dio.cpp - AHI Extended API

Functions with the _MW suffix are custom extensions not present in the AHI library.

bAHI_DoEnableOutputsEx_MW()

bool_t bAHI_DoEnableOutputsEx_MW(
    bool_t bEnableDO0, bool_t bEnableDO1);

Configures DO0 and DO1 as outputs.
This function was added because bAHI_DoEnableOutputs() configures both ports simultaneously.

vAHI_DioInterruptDisablePinsIntWhenChanged_MW(), vAHI_DioInterruptReavtivate_MW()

void vAHI_DioInterruptDisablePinsIntWhenChanged_MW(bool_t bSet);
void vAHI_DioInterruptReavtivate_MW();

Temporarily disables interrupts for pins where an interrupt has been detected.

• When called with bSet set to TRUE, interrupts for the affected pins are temporarily disabled when a DIO interrupt occurs.
• For inputs such as mechanical buttons with significant chattering, enable this setting and call vAHI_DioInterruptReavtivate_MW() after a certain time has passed since the interrupt to resume interrupts.

vAHI_DioOnSleep_MW()

void vAHI_DioOnSleep_MW();

An internal processing function not intended to be called by users.
It handles DIO interrupt-related processing before entering sleep, specifically configuring the DIO wake-up pins.

vAHI_DioOnWakeup_MW()

void vAHI_DioOnWakeup_MW(bool_t b_init_2nd);

An internal processing function not intended to be called by users.
It handles DIO interrupt-related processing at wake-up and stores the pins that triggered the wake-up.

• When called with b_init_2nd set to false, it runs at the very early stage of the WarmMain() process to identify the wake-up sources.
• It is then called again with true just before the call to cbAppWarmStart(TRUE).

vAHI_DioRetentionRelease_MW()

void vAHI_DioRetentionRelease_MW();

Releases the DIO output state retention after waking up from sleep.
This function is used when waking from RAM-OFF sleep and inside cbAppColdStart().

On JN518X, the register setting (SYSCON->RETENTIONCTRL) to retain DIO output states is configured before entering sleep.
DIO pins with output settings retain their states as configured in the register, and after waking from sleep, the output states remain until the register settings are changed. Calling this function releases the output state retention.

To restore the same configuration as before sleep, call vAHI_DioSetDirection() or vAHI_DioSetOutput() before calling this function to explicitly configure the output settings. This is necessary because DIO internal registers are cleared during sleep.

After the call to cbAppColdStart(), the TWENETmcu library performs the same process as this function. To avoid unintended HI/LO transitions on ports, configure the port outputs inside cbAppColdStart().

Others

Notes When Not Using This Library

Do not call functions from this library. Even if you do not call them, this library still depends on the TWENETmcu and TWENETlib libraries.

Refer to the following to resolve dependencies:

• Regarding interrupt pins when performing sleep procedures:
  • You need to adjust vAHI_DioOnSleep_MW() and vAHI_DioOnWakeup_MW().
    • These two functions are called from vAHI_OnSleep_MW() and vAHI_OnWakeup_MW() in TWENETcmpt.
  • The vAHI_OnSleep_MW() function depends on the closed-source TWENETlib library.
    • In vAHI_DioOnSleep_MW(), specify the PIO bitmap for wake-up interrupt detection in __twenet_ioport_int_status. It is applied inside ToCoNet_vSleep() to execute sleep properly.
  • vAHI_OnWakeup_MW() and vAHI_DioOnWakeup_MW() are called within the TWENETmcu library source. Modify the processing as needed.