/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2025 Oxide Computer Company
 */

#ifndef _SYS_I2C_IOCTL_H
#define _SYS_I2C_IOCTL_H

/*
 * Userland i2c requests.
 */

#include <sys/types.h>
#include <sys/i2c/i2c.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * This is a private property to aid nexus type discovery.
 */
#define I2C_NEXUS_TYPE_PROP     "i2c-nexus-type"
#define I2C_NEXUS_TYPE_PORT     "port"
#define I2C_NEXUS_TYPE_CTRL     "controller"
#define I2C_NEXUS_TYPE_MUX      "mux"

/*
 * Base user ioctl type.
 */
#define UI2C_IOCTL      (('i' << 24) | ('2' << 16) | ('c' << 8))

#define UI2C_IOCTL_CTRL_NPROPS          (UI2C_IOCTL | 0x00)
typedef struct ui2c_ctrl_nprops {
        uint16_t ucp_nstd;
        uint16_t ucp_npriv;
} ui2c_ctrl_nprops_t;

#define UI2C_IOCTL_CTRL_PROP_INFO       (UI2C_IOCTL | 0x01)

/*
 * Get information about a property.
 */
typedef struct ui2c_prop_info {
        i2c_error_t upi_error;
        uint32_t upi_prop;
        uint32_t upi_type;
        uint32_t upi_perm;
        uint32_t upi_def_len;
        uint32_t upi_pos_len;
        char upi_name[I2C_PROP_NAME_MAX];
        uint8_t upi_def[I2C_PROP_SIZE_MAX];
        uint8_t upi_pos[I2C_PROP_SIZE_MAX];
} ui2c_prop_info_t;

#define UI2C_IOCTL_CTRL_PROP_GET        (UI2C_IOCTL | 0x02)
#define UI2C_IOCTL_CTRL_PROP_SET        (UI2C_IOCTL | 0x03)

/*
 * Get and set a property. up_size is used to indicate how many bytes in
 * up_value are valid on a property set and is filled in on a property get.
 */
typedef struct ui2c_prop {
        i2c_error_t up_error;
        uint32_t up_prop;
        uint32_t up_size;
        uint8_t up_value[I2C_PROP_SIZE_MAX];
} ui2c_prop_t;

/*
 * These ioctls are used to add and remove an i2c device from the system. The
 * device will be added or removed directly under the port that the ioctl is
 * performed upon, this may be a controller or a mux. When adding a device, the
 * address must by unique within the port and any upstream ports. See
 * uts/common/io/i2c/i2cnex/i2cnex_addr.c for more background.
 *
 * When adding a structure, the nvlist is used. When removing it, we just pass
 * an address in using the second structure. The nvlist is due to the assumption
 * that things are going to get more complex eventually and need to include
 * things like properties. Either way, the intent is that this is private to
 * libi2c and it can change.
 */
#define UI2C_IOCTL_DEVICE_ADD           (UI2C_IOCTL | 0x04)
#define UI2C_IOCTL_DEVICE_REMOVE        (UI2C_IOCTL | 0x05)

#define UI2C_IOCTL_NVL_MAX_SIZE 0x4000          /* 16 KiB */
#define UI2C_IOCTL_NVL_ADDR     "address"       /* uint16_t */
#define UI2C_IOCTL_NVL_TYPE     "type"          /* uint16_t */
#define UI2C_IOCTL_NVL_NAME     "name"          /* string */
#define UI2C_IOCTL_NVL_COMPAT   "compat"        /* string[] (optional) */
#define UI2C_IOCTL_NVL_NCOMPAT_MAX      32      /* max compat[] length */

typedef struct ui2c_dev {
        i2c_error_t uda_error;
        uintptr_t uda_nvl;
        size_t uda_nvl_len;
} ui2c_dev_add_t;

typedef struct ui2c_dev_rem {
        i2c_error_t udr_error;
        i2c_addr_t udr_addr;
} ui2c_dev_rem_t;

/*
 * These commands are used to issue a request. Today, these can target any port.
 * If the port is downstream of a mux, the mux will be set up appropriately to
 * reach that port. These use the shared i2c_req_t and smbus_req_t found in
 * <sys/i2c/i2c.h>.
 *
 * In the future, we may want to have this work on a device. If we did, it would
 * be the same thing, but constrain the address in question to one that a
 * device actually had from the kernel's perspective.
 */
#define UI2C_IOCTL_I2C_REQ              (UI2C_IOCTL | 0x06)
#define UI2C_IOCTL_SMBUS_REQ            (UI2C_IOCTL | 0x07)

/*
 * Get information about a port and the addresses that exist underneath it.
 */
#define UI2C_IOCTL_PORT_INFO            (UI2C_IOCTL | 0x08)

typedef struct ui2c_port_addr_info {
        bool pai_downstream;
        uint8_t pai_ndevs;
        major_t pai_major;
        uint16_t pai_pad;
} ui2c_port_addr_info_t;

typedef struct ui2c_port_info {
        i2c_error_t upo_error;
        uint32_t upo_portno;
        uint32_t upo_ndevs;
        uint32_t upo_ndevs_ds;
        ui2c_port_addr_info_t upo_7b[1 << 7];
} ui2c_port_info_t;

/*
 * Get information about about a device and the kinds of addresses it uses.
 */
#define UI2C_IOCTL_DEV_INFO             (UI2C_IOCTL | 0x09)

typedef enum ui2c_dev_flags {
        UI2C_DEV_F_MUX = 1 << 0
} ui2c_dev_flags_t;

typedef struct ui2c_dev_info {
        i2c_error_t udi_error;
        i2c_addr_t udi_primary;
        uint32_t udi_flags;
        uint8_t udi_7b[1 << 7];
} ui2c_dev_info_t;

/*
 * Get information about a mux.
 */
#define UI2C_IOCTL_MUX_INFO             (UI2C_IOCTL | 0x0a)

typedef struct ui2c_mux_info {
        i2c_error_t umi_error;
        uint32_t umi_nports;
} ui2c_mux_info_t;

#if defined(_KERNEL) && defined(_SYSCALL32)
#pragma pack(4)
typedef struct {
        i2c_error_t uda_error;
        uintptr32_t uda_nvl;
        size32_t uda_nvl_len;
} ui2c_dev_add32_t;

#pragma pack() /* pack(4) */
#endif  /* _KERNEL && _SYSCALL32 */

#ifdef __cplusplus
}
#endif

#endif /* _SYS_I2C_IOCTL_H */