/*
 * 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 2019 Joyent, Inc.
 */

/*
 * Memory decoding logic.
 *
 * This file is part of the 'imc' driver on x86. It supports taking a physical
 * address and determining what the corresponding DIMM is. This is shared
 * between the kernel and userland for easier testing.
 *
 * For more information about the different parts of the decoding process,
 * please see the file 'uts/i86pc/io/imc/imc.c'.
 */

#include <sys/sysmacros.h>

#ifndef _KERNEL
#include <stdint.h>
#include <strings.h>
#define BITX(u, h, l)   (((u) >> (l)) & ((1LU << ((h) - (l) + 1LU)) - 1LU))
#endif  /* !_KERNEL */

#include "imc.h"

/*
 * Address ranges for decoding system addresses. There are three ranges that
 * exist on x86, traditional DOS memory (hi 640 KiB), low memory, and high
 * memory. Low memory always starts at 1 MiB and high memory always starts at 4
 * GiB. The upper bounds of these ranges is based on registers on the system.
 */
#define IMC_DECODE_CONV_BASE    0UL
#define IMC_DECODE_CONV_MAX     0x00009ffffULL  /* 640 KiB - 1 */
#define IMC_DECODE_LOW_BASE     0x000100000ULL  /* 1 M */
#define IMC_DECODE_HIGH_BASE    0x100000000ULL /* 4 GiB */

typedef struct imc_legacy_range {
        uint64_t        ilr_base;
        size_t          ilr_len;
        const char      *ilr_desc;
} imc_legacy_range_t;

/*
 * These represent regions of memory that are reserved for use and will not be
 * decoded by DRAM.
 */
static imc_legacy_range_t imc_legacy_ranges[] = {
        { 0x00000A0000ULL,      128 * 1024,     "VGA" },
        { 0x00000C0000ULL,      256 * 1024,     "PAM" },
        { 0x0000F00000ULL,      1024 * 1024,    "Reserved" },
        { 0x00FE000000ULL,      32 * 1024 * 1024, "Unknown" },
        { 0x00FF000000ULL,      16 * 1024 * 1024, "Firmware" },
        { 0x00FED20000ULL,      384 * 1024,     "TXT" },
        { 0x00FED00000ULL,      1024 * 1024,    "PCH" },
        { 0x00FEC00000ULL,      1024 * 1024,    "IOAPIC" },
        { 0x00FEB80000ULL,      512 * 1024,     "Reserved" },
        { 0x00FEB00000ULL,      64 * 1024,      "Reserved" }
};

/*
 * Determine whether or not this address is in one of the reserved regions or if
 * it falls outside of the explicit DRAM ranges.
 */
static boolean_t
imc_decode_addr_resvd(const imc_t *imc, imc_decode_state_t *dec)
{
        uint_t i;
        const imc_sad_t *sad;

        for (i = 0; i < ARRAY_SIZE(imc_legacy_ranges); i++) {
                uint64_t end = imc_legacy_ranges[i].ilr_base +
                    imc_legacy_ranges[i].ilr_len;

                if (dec->ids_pa >= imc_legacy_ranges[i].ilr_base &&
                    dec->ids_pa < end) {
                        dec->ids_fail = IMC_DECODE_F_LEGACY_RANGE;
                        dec->ids_fail_data = i;
                        return (B_TRUE);
                }
        }

        /*
         * For checking and determining whether or not we fit in DRAM, we need
         * to check against the top of low memory and the top of high memory.
         * While we technically have this information on a per-socket basis, we
         * have to rely on the fact that both processors have the same
         * information. A requirement which if not true, would lead to chaos
         * depending on what socket we're running on.
         */
        sad = &imc->imc_sockets[0].isock_sad;
        if (sad->isad_valid != IMC_SAD_V_VALID) {
                dec->ids_fail = IMC_DECODE_F_BAD_SAD;
                return (B_TRUE);
        }

        /*
         * An address may fall into three ranges. It may fall into conventional
         * memory. It may fall into low memory. It may fall into high memory.
         * The conventional memory range is inclusive at the top. The others
         * have been translated such that they are uniformly exclusive at the
         * top. Because the bottom of conventional memory is at zero, the
         * compiler will be angry if we compare against IMC_DECODE_CONV_BASE as
         * it is always true.
         */
        if (dec->ids_pa <= IMC_DECODE_CONV_MAX) {
                return (B_FALSE);
        }

        if (dec->ids_pa >= IMC_DECODE_LOW_BASE &&
            dec->ids_pa < sad->isad_tolm) {
                return (B_FALSE);
        }

        if (dec->ids_pa >= IMC_DECODE_HIGH_BASE &&
            dec->ids_pa < sad->isad_tohm) {
                return (B_FALSE);
        }

        /*
         * Memory fell outside of the valid range. It's not for us.
         */
        dec->ids_fail = IMC_DECODE_F_OUTSIDE_DRAM;
        return (B_TRUE);
}

static uint_t
imc_decode_sad_interleave(const imc_sad_rule_t *rule, uint64_t pa)
{
        uint_t itgt = 0;

        switch (rule->isr_imode) {
        case IMC_SAD_IMODE_8t6:
                if (rule->isr_a7mode) {
                        itgt = BITX(pa, 9, 9);
                        itgt |= (BITX(pa, 8, 7) << 1);
                } else {
                        itgt = BITX(pa, 8, 6);
                }
                break;
        case IMC_SAD_IMODE_8t6XOR:
                if (rule->isr_a7mode) {
                        itgt = BITX(pa, 9, 9);
                        itgt |= (BITX(pa, 8, 7) << 1);
                } else {
                        itgt = BITX(pa, 8, 6);
                }
                itgt ^= BITX(pa, 18, 16);
                break;
        case IMC_SAD_IMODE_10t8:
                itgt = BITX(pa, 10, 8);
                break;
        case IMC_SAD_IMODE_14t12:
                itgt = BITX(pa, 14, 12);
                break;
        case IMC_SAD_IMODE_32t30:
                itgt = BITX(pa, 32, 30);
                break;
        }

        return (itgt);
}

/*
 * Use the system address decoder to try and find a valid SAD entry for this
 * address. We always use socket zero's SAD as the SAD rules should be the same
 * between the different sockets.
 */
static boolean_t
imc_decode_sad(const imc_t *imc, imc_decode_state_t *dec)
{
        uint_t i, ileaveidx;
        uint8_t ileavetgt;
        uint32_t nodeid, tadid, channelid;
        uint64_t base;
        const imc_socket_t *socket = &imc->imc_sockets[0];
        const imc_sad_t *sad = &socket->isock_sad;
        const imc_sad_rule_t *rule;
        boolean_t loop = B_FALSE;

        /*
         * Note, all SAD rules have been adjusted so that they are uniformly
         * exclusive.
         */
start:
        for (rule = NULL, i = 0, base = 0; i < sad->isad_nrules; i++) {
                rule = &sad->isad_rules[i];

                if (rule->isr_enable && dec->ids_pa >= base &&
                    dec->ids_pa < rule->isr_limit) {
                        break;
                }

                base = rule->isr_limit;
        }

        if (rule == NULL || i == sad->isad_nrules) {
                dec->ids_fail = IMC_DECODE_F_NO_SAD_RULE;
                return (B_FALSE);
        }

        /*
         * Store the SAD rule in the decode information for debugging's sake.
         */
        dec->ids_sad = sad;
        dec->ids_sad_rule = rule;

        /*
         * We have found a SAD rule. We now need to transform that into the
         * corresponding target based on its mode, etc. The way we do this
         * varies based on the generation.
         *
         * The first thing we need to do is to figure out the target in the
         * interleave list.
         */
        ileaveidx = imc_decode_sad_interleave(rule, dec->ids_pa);
        if (ileaveidx >= rule->isr_ntargets) {
                dec->ids_fail = IMC_DECODE_F_BAD_SAD_INTERLEAVE;
                dec->ids_fail_data = ileaveidx;
                return (B_FALSE);
        }
        ileavetgt = rule->isr_targets[ileaveidx];
        if (imc->imc_gen >= IMC_GEN_SKYLAKE &&
            IMC_SAD_ILEAVE_SKX_LOCAL(ileavetgt) == 0) {
                /*
                 * If we're in this case, the interleave rule said we had a
                 * remote target. That means we need to find the correct SAD
                 * based on the Node ID and then do all of this over again.
                 */
                nodeid = IMC_SAD_ILEAVE_SKX_TARGET(ileavetgt);

                if (loop) {
                        dec->ids_fail = IMC_DECODE_F_SAD_SEARCH_LOOP;
                        return (B_FALSE);
                }

                for (i = 0; i < imc->imc_nsockets; i++) {
                        if (imc->imc_sockets[i].isock_valid ==
                            IMC_SOCKET_V_VALID &&
                            imc->imc_sockets[i].isock_nodeid == nodeid) {
                                socket = &imc->imc_sockets[i];
                                sad = &imc->imc_sockets[i].isock_sad;
                                loop = B_TRUE;
                                goto start;
                        }
                }

                dec->ids_fail = IMC_DECODE_F_BAD_REMOTE_MC_ROUTE;
                dec->ids_fail_data = nodeid;
                return (B_FALSE);
        }

        /*
         * On some platforms we need to derive the target channel based on the
         * physical address and additional rules in the SAD. If we do, do that
         * here. The idea is that this may overrule the memory channel route
         * table target that was determined from the SAD rule.
         */
        if (rule->isr_need_mod3) {
                uint64_t addr;
                uint8_t channel;

                switch (rule->isr_mod_mode) {
                case IMC_SAD_MOD_MODE_45t6:
                        addr = dec->ids_pa >> 6;
                        break;
                case IMC_SAD_MOD_MODE_45t8:
                        addr = dec->ids_pa >> 8;
                        break;
                case IMC_SAD_MOD_MODE_45t12:
                        addr = dec->ids_pa >> 12;
                        break;
                default:
                        dec->ids_fail = IMC_DECODE_F_SAD_BAD_MOD;
                        return (B_FALSE);
                }

                switch (rule->isr_mod_type) {
                case IMC_SAD_MOD_TYPE_MOD3:
                        channel = (addr % 3) << 1;
                        channel |= ileavetgt & 1;
                        break;
                case IMC_SAD_MOD_TYPE_MOD2_01:
                        channel = (addr % 2) << 1;
                        channel |= ileavetgt & 1;
                        break;
                case IMC_SAD_MOD_TYPE_MOD2_12:
                        channel = (addr % 2) << 2;
                        channel |= (~addr % 2) << 1;
                        channel |= ileavetgt & 1;
                        break;
                case IMC_SAD_MOD_TYPE_MOD2_02:
                        channel = (addr % 2) << 2;
                        channel |= ileavetgt & 1;
                        break;
                default:
                        dec->ids_fail = IMC_DECODE_F_SAD_BAD_MOD;
                        return (B_FALSE);
                }

                ileavetgt = channel;
        }

        switch (imc->imc_gen) {
        case IMC_GEN_SANDY:
                /*
                 * Sandy Bridge systems only have a single home agent, so the
                 * interleave target is always the node id.
                 */
                nodeid = ileavetgt;
                tadid = 0;
                channelid = UINT32_MAX;
                break;
        case IMC_GEN_IVY:
        case IMC_GEN_HASWELL:
        case IMC_GEN_BROADWELL:
                /*
                 * On these generations, the interleave NodeID in the SAD
                 * encodes both the nodeid and the home agent ID that we care
                 * about.
                 */
                nodeid = IMC_NODEID_IVY_BRD_UPPER(ileavetgt) |
                    IMC_NODEID_IVY_BRD_LOWER(ileavetgt);
                tadid = IMC_NODEID_IVY_BRD_HA(ileavetgt);
                channelid = UINT32_MAX;
                break;
        case IMC_GEN_SKYLAKE:
                /*
                 * On Skylake generation systems we take the interleave target
                 * and use that to look up both the memory controller and the
                 * physical channel in the route table. The nodeid is already
                 * known because its SAD rules redirect us.
                 */
                nodeid = socket->isock_nodeid;
                if (ileavetgt > IMC_SAD_ILEAVE_SKX_MAX) {
                        dec->ids_fail = IMC_DECODE_F_BAD_SAD_INTERLEAVE;
                        dec->ids_fail_data = ileavetgt;
                        return (B_FALSE);
                }
                ileavetgt = IMC_SAD_ILEAVE_SKX_TARGET(ileavetgt);
                if (ileavetgt > sad->isad_mcroute.ismc_nroutes) {
                        dec->ids_fail = IMC_DECODE_F_BAD_SAD_INTERLEAVE;
                        dec->ids_fail_data = ileavetgt;
                        return (B_FALSE);
                }
                tadid = sad->isad_mcroute.ismc_mcroutes[ileavetgt].ismce_imc;
                channelid =
                    sad->isad_mcroute.ismc_mcroutes[ileavetgt].ismce_pchannel;
                break;
        default:
                nodeid = tadid = channelid = UINT32_MAX;
                break;
        }

        /*
         * Map to the correct socket based on the nodeid. Make sure that we have
         * a valid TAD.
         */
        dec->ids_socket = NULL;
        for (i = 0; i < imc->imc_nsockets; i++) {
                if (imc->imc_sockets[i].isock_nodeid == nodeid) {
                        dec->ids_socket = &imc->imc_sockets[i];
                        break;
                }
        }
        if (dec->ids_socket == NULL) {
                dec->ids_fail = IMC_DECODE_F_SAD_BAD_SOCKET;
                dec->ids_fail_data = nodeid;
                return (B_FALSE);
        }

        if (tadid >= dec->ids_socket->isock_ntad) {
                dec->ids_fail = IMC_DECODE_F_SAD_BAD_TAD;
                dec->ids_fail_data = tadid;
                return (B_FALSE);
        }

        dec->ids_nodeid = nodeid;
        dec->ids_tadid = tadid;
        dec->ids_channelid = channelid;
        dec->ids_tad = &dec->ids_socket->isock_tad[tadid];
        dec->ids_mc = &dec->ids_socket->isock_imcs[tadid];

        return (B_TRUE);
}

/*
 * For Sandy Bridge through Broadwell we need to decode the memory channel that
 * we're targeting. This is determined based on the number of ways that the
 * socket and channel are supposed to be interleaved. The TAD has a target
 * channel list sitting with the TAD rule. To figure out the appropriate index,
 * the algorithm is roughly:
 *
 *    idx = [(dec->ids_pa >> 6) / socket-ways] % channel-ways
 *
 * The shift by six, comes from taking the number of bits that are in theory in
 * the cache line size. Of course, if things were this simple, that'd be great.
 * The first complication is a7mode / MCChanShiftUpEnable. When this is enabled,
 * more cache lines are used for this. The next complication comes when the
 * feature MCChanHashEn is enabled. This means that we have to hash the
 * resulting address before we do the modulus based on the number of channel
 * ways.
 *
 * The last, and most complicated problem is when the number of channel ways is
 * set to three. When this is the case, the base address of the range may not
 * actually start at index zero. The nominal solution is to use the offset
 * that's programmed on a per-channel basis to offset the system address.
 * However, to get that information we would have to know what channel we're on,
 * which is what we're trying to figure out. Regretfully, proclaim that we can't
 * in this case.
 */
static boolean_t
imc_decode_tad_channel(const imc_t *imc, imc_decode_state_t *dec)
{
        uint64_t index;
        const imc_tad_rule_t *rule = dec->ids_tad_rule;

        index = dec->ids_pa >> 6;
        if ((dec->ids_tad->itad_flags & IMC_TAD_FLAG_CHANSHIFT) != 0) {
                index = index >> 1;
        }

        /*
         * When performing a socket way equals three comparison, this would not
         * work.
         */
        index = index / rule->itr_sock_way;

        if ((dec->ids_tad->itad_flags & IMC_TAD_FLAG_CHANHASH) != 0) {
                uint_t i;
                for (i = 12; i < 28; i += 2) {
                        uint64_t shift = (dec->ids_pa >> i) & 0x3;
                        index ^= shift;
                }
        }

        index %= rule->itr_chan_way;
        if (index >= rule->itr_ntargets) {
                dec->ids_fail = IMC_DECODE_F_TAD_BAD_TARGET_INDEX;
                dec->ids_fail_data = index;
                return (B_FALSE);
        }

        dec->ids_channelid = rule->itr_targets[index];
        return (B_TRUE);
}

static uint_t
imc_tad_gran_to_shift(const imc_tad_t *tad, imc_tad_gran_t gran)
{
        uint_t shift = 0;

        switch (gran) {
        case IMC_TAD_GRAN_64B:
                shift = 6;
                if ((tad->itad_flags & IMC_TAD_FLAG_CHANSHIFT) != 0) {
                        shift++;
                }
                break;
        case IMC_TAD_GRAN_256B:
                shift = 8;
                break;
        case IMC_TAD_GRAN_4KB:
                shift = 12;
                break;
        case IMC_TAD_GRAN_1GB:
                shift = 30;
                break;
        }

        return (shift);
}

static boolean_t
imc_decode_tad(const imc_t *imc, imc_decode_state_t *dec)
{
        uint_t i, tadruleno;
        uint_t sockshift, chanshift, sockmask, chanmask;
        uint64_t off, chanaddr;
        const imc_tad_t *tad = dec->ids_tad;
        const imc_mc_t *mc = dec->ids_mc;
        const imc_tad_rule_t *rule = NULL;
        const imc_channel_t *chan;

        /*
         * The first step in all of this is to determine which TAD rule applies
         * for this address.
         */
        for (i = 0; i < tad->itad_nrules; i++) {
                rule = &tad->itad_rules[i];

                if (dec->ids_pa >= rule->itr_base &&
                    dec->ids_pa < rule->itr_limit) {
                        break;
                }
        }

        if (rule == NULL || i == tad->itad_nrules) {
                dec->ids_fail = IMC_DECODE_F_NO_TAD_RULE;
                return (B_FALSE);
        }
        tadruleno = i;
        dec->ids_tad_rule = rule;

        /*
         * Check if our TAD rule requires 3-way interleaving on the channel. We
         * basically can't do that right now. For more information, see the
         * comment above imc_decode_tad_channel().
         */
        if (rule->itr_chan_way == 3) {
                dec->ids_fail = IMC_DECODE_F_TAD_3_ILEAVE;
                return (B_FALSE);
        }

        /*
         * On some platforms, we need to now calculate the channel index from
         * this. The way that we calculate this is nominally straightforward,
         * but complicated by a number of different issues.
         */
        switch (imc->imc_gen) {
        case IMC_GEN_SANDY:
        case IMC_GEN_IVY:
        case IMC_GEN_HASWELL:
        case IMC_GEN_BROADWELL:
                if (!imc_decode_tad_channel(imc, dec)) {
                        return (B_FALSE);
                }
                break;
        default:
                /*
                 * On Skylake and newer platforms we should have already decoded
                 * the target channel based on using the memory controller route
                 * table above.
                 */
                break;
        }

        /*
         * We initialize ids_channelid to UINT32_MAX, so this should make sure
         * that we catch an incorrect channel as well.
         */
        if (dec->ids_channelid >= mc->icn_nchannels) {
                dec->ids_fail = IMC_DECODE_F_BAD_CHANNEL_ID;
                dec->ids_fail_data = dec->ids_channelid;
                return (B_FALSE);
        }
        chan = &mc->icn_channels[dec->ids_channelid];
        dec->ids_chan = chan;

        if (tadruleno >= chan->ich_ntad_offsets) {
                dec->ids_fail = IMC_DECODE_F_BAD_CHANNEL_TAD_OFFSET;
                dec->ids_fail_data = tadruleno;
                return (B_FALSE);
        }

        /*
         * Now we can go ahead and calculate the channel address, which is
         * roughly equal to:
         *
         * chan_addr = (sys_addr - off) / (chan way * sock way).
         *
         * The catch is that we want to preserve the low bits where possible.
         * The number of bits is based on the interleaving granularities, the
         * way that's calculated is based on information in the TAD rule.
         * However, if a7mode is enabled on Ivy Bridge through Broadwell, then
         * we need to add one to that. So we will save the smallest number of
         * bits that are left after interleaving.
         *
         * Because the interleaving occurs at different granularities, we need
         * to break this into two discrete steps, one where we apply the socket
         * interleaving and one where we apply the channel interleaving,
         * shifting and dividing at each step.
         */
        off = chan->ich_tad_offsets[tadruleno];
        if (off > dec->ids_pa) {
                dec->ids_fail = IMC_DECODE_F_CHANOFF_UNDERFLOW;
                return (B_FALSE);
        }
        chanshift = imc_tad_gran_to_shift(tad, rule->itr_chan_gran);
        sockshift = imc_tad_gran_to_shift(tad, rule->itr_sock_gran);
        chanmask = (1 << chanshift) - 1;
        sockmask = (1 << sockshift) - 1;

        chanaddr = dec->ids_pa - off;
        chanaddr >>= sockshift;
        chanaddr /= rule->itr_sock_way;
        chanaddr <<= sockshift;
        chanaddr |= dec->ids_pa & sockmask;
        chanaddr >>= chanshift;
        chanaddr /= rule->itr_chan_way;
        chanaddr <<= chanshift;
        chanaddr |= dec->ids_pa & chanmask;

        dec->ids_chanaddr = chanaddr;

        return (B_TRUE);
}

static boolean_t
imc_decode_rir(const imc_t *imc, imc_decode_state_t *dec)
{
        const imc_mc_t *mc = dec->ids_mc;
        const imc_channel_t *chan = dec->ids_chan;
        const imc_rank_ileave_t *rir = NULL;
        const imc_rank_ileave_entry_t *rirtarg;
        const imc_dimm_t *dimm;
        uint32_t shift, index;
        uint_t i, dimmid, rankid;
        uint64_t mask, base, rankaddr;

        if (mc->icn_closed) {
                shift = IMC_PAGE_BITS_CLOSED;
        } else {
                shift = IMC_PAGE_BITS_OPEN;
        }
        mask = (1UL << shift) - 1;

        for (i = 0, base = 0; i < chan->ich_nrankileaves; i++) {
                rir = &chan->ich_rankileaves[i];
                if (rir->irle_enabled && dec->ids_chanaddr >= base &&
                    dec->ids_chanaddr < rir->irle_limit) {
                        break;
                }

                base = rir->irle_limit;
        }

        if (rir == NULL || i == chan->ich_nrankileaves) {
                dec->ids_fail = IMC_DECODE_F_NO_RIR_RULE;
                return (B_FALSE);
        }
        dec->ids_rir = rir;

        /*
         * Determine the index of the rule that we care about. This is done by
         * shifting the address based on the open and closed page bits and then
         * just modding it by the number of ways in question.
         */
        index = (dec->ids_chanaddr >> shift) % rir->irle_nways;
        if (index >= rir->irle_nentries) {
                dec->ids_fail = IMC_DECODE_F_BAD_RIR_ILEAVE_TARGET;
                dec->ids_fail_data = index;
                return (B_FALSE);
        }
        rirtarg = &rir->irle_entries[index];

        /*
         * The rank interleaving register has information about a physical rank
         * target. This is within the notion of the physical chip selects that
         * exist. While the memory controller only has eight actual chip
         * selects, the physical values that are programmed depend a bit on the
         * underlying hardware. Effectively, in this ID space, each DIMM has
         * four ranks associated with it. Even when we only have two ranks with
         * each physical channel, they'll be programmed so we can simply do the
         * following match:
         *
         * DIMM = rank id / 4
         * RANK = rank id % 4
         */
        dec->ids_physrankid = rirtarg->irle_target;
        dimmid = dec->ids_physrankid / 4;
        rankid = dec->ids_physrankid % 4;

        if (dimmid >= chan->ich_ndimms) {
                dec->ids_fail = IMC_DECODE_F_BAD_DIMM_INDEX;
                dec->ids_fail_data = dimmid;
                return (B_FALSE);
        }

        dimm = &chan->ich_dimms[dimmid];
        if (!dimm->idimm_present) {
                dec->ids_fail = IMC_DECODE_F_DIMM_NOT_PRESENT;
                return (B_FALSE);
        }
        dec->ids_dimmid = dimmid;
        dec->ids_dimm = dimm;

        if (rankid >= dimm->idimm_nranks) {
                dec->ids_fail = IMC_DECODE_F_BAD_DIMM_RANK;
                dec->ids_fail_data = rankid;
                return (B_FALSE);
        }
        dec->ids_rankid = rankid;

        /*
         * Calculate the rank address. We need to divide the address by the
         * number of rank ways and then or in the lower bits.
         */
        rankaddr = dec->ids_chanaddr;
        rankaddr >>= shift;
        rankaddr /= rir->irle_nways;
        rankaddr <<= shift;
        rankaddr |= dec->ids_chanaddr & mask;

        if (rirtarg->irle_offset > rankaddr) {
                dec->ids_fail = IMC_DECODE_F_RANKOFF_UNDERFLOW;
                return (B_FALSE);
        }
        rankaddr -= rirtarg->irle_offset;
        dec->ids_rankaddr = rankaddr;

        return (B_TRUE);
}

boolean_t
imc_decode_pa(const imc_t *imc, uint64_t pa, imc_decode_state_t *dec)
{
        bzero(dec, sizeof (*dec));
        dec->ids_pa = pa;
        dec->ids_nodeid = dec->ids_tadid = dec->ids_channelid = UINT32_MAX;

        /*
         * We need to rely on socket zero's information. Make sure that it both
         * exists and is considered valid.
         */
        if (imc->imc_nsockets < 1 ||
            imc->imc_sockets[0].isock_valid != IMC_SOCKET_V_VALID) {
                dec->ids_fail = IMC_DECODE_F_BAD_SOCKET;
                dec->ids_fail_data = 0;
                return (B_FALSE);
        }

        /*
         * First, we need to make sure that the PA we've been given actually is
         * meant to target a DRAM address. This address may fall to MMIO, MMCFG,
         * be an address that's outside of DRAM, or belong to a legacy address
         * range that is interposed.
         */
        if (imc_decode_addr_resvd(imc, dec)) {
                return (B_FALSE);
        }

        /*
         * Now that we have this data, we want to go through and look at the
         * SAD. The SAD will point us to a specific socket and an IMC / home
         * agent on that socket which will tell us which TAD we need to use.
         */
        if (!imc_decode_sad(imc, dec)) {
                return (B_FALSE);
        }

        /*
         * The decoded SAD information has pointed us a TAD. We need to use this
         * to point us to the corresponding memory channel and the corresponding
         * address on the channel.
         */
        if (!imc_decode_tad(imc, dec)) {
                return (B_FALSE);
        }

        /*
         * Use the rank interleaving data to determine which DIMM this is, the
         * relevant rank, and the rank address.
         */
        if (!imc_decode_rir(imc, dec)) {
                return (B_FALSE);
        }

        return (B_TRUE);
}