Hello,
> -----Original Message-----
> From: Jonas Gorski <jonas.gorski@gmail.com>
> Sent: Tuesday, March 7, 2023 1:31 AM
> To: Mahapatra, Amit Kumar <amit.kumar-mahapatra@amd.com>
> Cc: broonie@kernel.org; miquel.raynal@bootlin.com; richard@nod.at;
> vigneshr@ti.com; jic23@kernel.org; tudor.ambarus@microchip.com;
> pratyush@kernel.org; Mehta, Sanju <Sanju.Mehta@amd.com>; chin-
> ting_kuo@aspeedtech.com; clg@kaod.org; kdasu.kdev@gmail.com;
> f.fainelli@gmail.com; rjui@broadcom.com; sbranden@broadcom.com;
> eajames@linux.ibm.com; olteanv@gmail.com; han.xu@nxp.com;
> john.garry@huawei.com; shawnguo@kernel.org; s.hauer@pengutronix.de;
> narmstrong@baylibre.com; khilman@baylibre.com;
> matthias.bgg@gmail.com; haibo.chen@nxp.com; linus.walleij@linaro.org;
> daniel@zonque.org; haojian.zhuang@gmail.com; robert.jarzmik@free.fr;
> agross@kernel.org; bjorn.andersson@linaro.org; heiko@sntech.de;
> krzysztof.kozlowski@linaro.org; andi@etezian.org;
> mcoquelin.stm32@gmail.com; alexandre.torgue@foss.st.com;
> wens@csie.org; jernej.skrabec@gmail.com; samuel@sholland.org;
> masahisa.kojima@linaro.org; jaswinder.singh@linaro.org;
> rostedt@goodmis.org; mingo@redhat.com; l.stelmach@samsung.com;
> davem@davemloft.net; edumazet@google.com; kuba@kernel.org;
> pabeni@redhat.com; alex.aring@gmail.com; stefan@datenfreihafen.org;
> kvalo@kernel.org; james.schulman@cirrus.com; david.rhodes@cirrus.com;
> tanureal@opensource.cirrus.com; rf@opensource.cirrus.com;
> perex@perex.cz; tiwai@suse.com; npiggin@gmail.com;
> christophe.leroy@csgroup.eu; mpe@ellerman.id.au; oss@buserror.net;
> windhl@126.com; yangyingliang@huawei.com;
> william.zhang@broadcom.com; kursad.oney@broadcom.com;
> anand.gore@broadcom.com; rafal@milecki.pl; git (AMD-Xilinx)
> <git@amd.com>; linux-spi@vger.kernel.org; linux-kernel@vger.kernel.org;
> joel@jms.id.au; andrew@aj.id.au; radu_nicolae.pirea@upb.ro;
> nicolas.ferre@microchip.com; alexandre.belloni@bootlin.com;
> claudiu.beznea@microchip.com; bcm-kernel-feedback-list@broadcom.com;
> fancer.lancer@gmail.com; kernel@pengutronix.de; festevam@gmail.com;
> linux-imx@nxp.com; jbrunet@baylibre.com;
> martin.blumenstingl@googlemail.com; avifishman70@gmail.com;
> tmaimon77@gmail.com; tali.perry1@gmail.com; venture@google.com;
> yuenn@google.com; benjaminfair@google.com; yogeshgaur.83@gmail.com;
> konrad.dybcio@somainline.org; alim.akhtar@samsung.com;
> ldewangan@nvidia.com; thierry.reding@gmail.com; jonathanh@nvidia.com;
> Simek, Michal <michal.simek@amd.com>; linux-aspeed@lists.ozlabs.org;
> openbmc@lists.ozlabs.org; linux-arm-kernel@lists.infradead.org; linux-rpi-
> kernel@lists.infradead.org; linux-amlogic@lists.infradead.org; linux-
> mediatek@lists.infradead.org; linux-arm-msm@vger.kernel.org; linux-
> rockchip@lists.infradead.org; linux-samsung-soc@vger.kernel.org; linux-
> stm32@st-md-mailman.stormreply.com; linux-sunxi@lists.linux.dev; linux-
> tegra@vger.kernel.org; netdev@vger.kernel.org; linux-
> wpan@vger.kernel.org; libertas-dev@lists.infradead.org; linux-
> wireless@vger.kernel.org; linux-mtd@lists.infradead.org; lars@metafoo.de;
> Michael.Hennerich@analog.com; linux-iio@vger.kernel.org;
> michael@walle.cc; palmer@dabbelt.com; linux-riscv@lists.infradead.org;
> alsa-devel@alsa-project.org; patches@opensource.cirrus.com; linuxppc-
> dev@lists.ozlabs.org; amitrkcian2002@gmail.com
> Subject: Re: [PATCH V5 09/15] spi: Add stacked and parallel memories
> support in SPI core
>
> Hi,
>
> On Mon, 6 Mar 2023 at 18:26, Amit Kumar Mahapatra <amit.kumar-
> mahapatra@amd.com> wrote:
> >
> > For supporting multiple CS the SPI device need to be aware of all the
> > CS values. So, the "chip_select" member in the spi_device structure is
> > now an array that holds all the CS values.
> >
> > spi_device structure now has a "cs_index_mask" member. This acts as an
> > index to the chip_select array. If nth bit of spi->cs_index_mask is
> > set then the driver would assert spi->chip_select[n].
> >
> > In parallel mode all the chip selects are asserted/de-asserted
> > simultaneously and each byte of data is stored in both devices, the
> > even bits in one, the odd bits in the other. The split is
> > automatically handled by the GQSPI controller. The GQSPI controller
> > supports a maximum of two flashes connected in parallel mode. A
> > "multi-cs-cap" flag is added in the spi controntroller data, through
> > ctlr->multi-cs-cap the spi core will make sure that the controller is
> > capable of handling multiple chip selects at once.
> >
> > For supporting multiple CS via GPIO the cs_gpiod member of the
> > spi_device structure is now an array that holds the gpio descriptor
> > for each chipselect.
> >
> > Multi CS support using GPIO is not tested due to unavailability of
> > necessary hardware setup.
> >
> > Signed-off-by: Amit Kumar Mahapatra <amit.kumar-
> mahapatra@amd.com>
> > ---
> > drivers/spi/spi.c | 213 +++++++++++++++++++++++++++-------------
> > include/linux/spi/spi.h | 34 +++++--
> > 2 files changed, 173 insertions(+), 74 deletions(-)
> >
> > diff --git a/drivers/spi/spi.c b/drivers/spi/spi.c index
> > 5866bf5813a4..8ec7f58fa111 100644
> > --- a/drivers/spi/spi.c
> > +++ b/drivers/spi/spi.c
> > @@ -613,7 +613,8 @@ static int spi_dev_check(struct device *dev, void
> *data)
> > struct spi_device *new_spi = data;
> >
> > if (spi->controller == new_spi->controller &&
> > - spi_get_chipselect(spi, 0) == spi_get_chipselect(new_spi, 0))
> > + spi_get_chipselect(spi, 0) == spi_get_chipselect(new_spi, 0) &&
> > + spi_get_chipselect(spi, 1) == spi_get_chipselect(new_spi,
> > + 1))
> > return -EBUSY;
>
> This will only reject new devices if both chip selects are identical, but not if
> they only share one, e.g. CS 1 + 2 vs 1 + 3, or 1 + 2 vs only 2, or if the order is
> different (1 + 2 vs 2 + 1 - haven't read the code too close to know if this is
> allowed/possible).
Agreed, will add in the next series.
Regards,
Amit
>
> Regards,
> Jonas
@@ -613,7 +613,8 @@ static int spi_dev_check(struct device *dev, void *data)
struct spi_device *new_spi = data;
if (spi->controller == new_spi->controller &&
- spi_get_chipselect(spi, 0) == spi_get_chipselect(new_spi, 0))
+ spi_get_chipselect(spi, 0) == spi_get_chipselect(new_spi, 0) &&
+ spi_get_chipselect(spi, 1) == spi_get_chipselect(new_spi, 1))
return -EBUSY;
return 0;
}
@@ -628,7 +629,7 @@ static int __spi_add_device(struct spi_device *spi)
{
struct spi_controller *ctlr = spi->controller;
struct device *dev = ctlr->dev.parent;
- int status;
+ int status, idx;
/*
* We need to make sure there's no other device with this
@@ -637,8 +638,7 @@ static int __spi_add_device(struct spi_device *spi)
*/
status = bus_for_each_dev(&spi_bus_type, NULL, spi, spi_dev_check);
if (status) {
- dev_err(dev, "chipselect %d already in use\n",
- spi_get_chipselect(spi, 0));
+ dev_err(dev, "chipselect %d already in use\n", spi_get_chipselect(spi, 0));
return status;
}
@@ -648,8 +648,10 @@ static int __spi_add_device(struct spi_device *spi)
return -ENODEV;
}
- if (ctlr->cs_gpiods)
- spi_set_csgpiod(spi, 0, ctlr->cs_gpiods[spi_get_chipselect(spi, 0)]);
+ if (ctlr->cs_gpiods) {
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++)
+ spi_set_csgpiod(spi, idx, ctlr->cs_gpiods[spi_get_chipselect(spi, idx)]);
+ }
/*
* Drivers may modify this initial i/o setup, but will
@@ -689,13 +691,15 @@ int spi_add_device(struct spi_device *spi)
{
struct spi_controller *ctlr = spi->controller;
struct device *dev = ctlr->dev.parent;
- int status;
+ int status, idx;
- /* Chipselects are numbered 0..max; validate. */
- if (spi_get_chipselect(spi, 0) >= ctlr->num_chipselect) {
- dev_err(dev, "cs%d >= max %d\n", spi_get_chipselect(spi, 0),
- ctlr->num_chipselect);
- return -EINVAL;
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++) {
+ /* Chipselects are numbered 0..max; validate. */
+ if (spi_get_chipselect(spi, idx) >= ctlr->num_chipselect) {
+ dev_err(dev, "cs%d >= max %d\n", spi_get_chipselect(spi, idx),
+ ctlr->num_chipselect);
+ return -EINVAL;
+ }
}
/* Set the bus ID string */
@@ -712,12 +716,15 @@ static int spi_add_device_locked(struct spi_device *spi)
{
struct spi_controller *ctlr = spi->controller;
struct device *dev = ctlr->dev.parent;
+ int idx;
- /* Chipselects are numbered 0..max; validate. */
- if (spi_get_chipselect(spi, 0) >= ctlr->num_chipselect) {
- dev_err(dev, "cs%d >= max %d\n", spi_get_chipselect(spi, 0),
- ctlr->num_chipselect);
- return -EINVAL;
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++) {
+ /* Chipselects are numbered 0..max; validate. */
+ if (spi_get_chipselect(spi, idx) >= ctlr->num_chipselect) {
+ dev_err(dev, "cs%d >= max %d\n", spi_get_chipselect(spi, idx),
+ ctlr->num_chipselect);
+ return -EINVAL;
+ }
}
/* Set the bus ID string */
@@ -965,58 +972,119 @@ static void spi_res_release(struct spi_controller *ctlr, struct spi_message *mes
static void spi_set_cs(struct spi_device *spi, bool enable, bool force)
{
bool activate = enable;
+ u32 cs_num = __ffs(spi->cs_index_mask);
+ int idx;
/*
- * Avoid calling into the driver (or doing delays) if the chip select
- * isn't actually changing from the last time this was called.
+ * In parallel mode all the chip selects are asserted/de-asserted
+ * at once
*/
- if (!force && ((enable && spi->controller->last_cs == spi_get_chipselect(spi, 0)) ||
- (!enable && spi->controller->last_cs != spi_get_chipselect(spi, 0))) &&
- (spi->controller->last_cs_mode_high == (spi->mode & SPI_CS_HIGH)))
- return;
-
- trace_spi_set_cs(spi, activate);
-
- spi->controller->last_cs = enable ? spi_get_chipselect(spi, 0) : -1;
- spi->controller->last_cs_mode_high = spi->mode & SPI_CS_HIGH;
-
- if ((spi_get_csgpiod(spi, 0) || !spi->controller->set_cs_timing) && !activate)
- spi_delay_exec(&spi->cs_hold, NULL);
-
- if (spi->mode & SPI_CS_HIGH)
- enable = !enable;
+ if ((spi->cs_index_mask & SPI_PARALLEL_CS_MASK) == SPI_PARALLEL_CS_MASK) {
+ spi->controller->last_cs_mode_high = spi->mode & SPI_CS_HIGH;
+
+ if ((spi_get_csgpiod(spi, 0) || !spi->controller->set_cs_timing) && !activate)
+ spi_delay_exec(&spi->cs_hold, NULL);
+
+ if (spi->mode & SPI_CS_HIGH)
+ enable = !enable;
+
+ if (spi_get_csgpiod(spi, 0) && spi_get_csgpiod(spi, 1)) {
+ if (!(spi->mode & SPI_NO_CS)) {
+ /*
+ * Historically ACPI has no means of the GPIO polarity and
+ * thus the SPISerialBus() resource defines it on the per-chip
+ * basis. In order to avoid a chain of negations, the GPIO
+ * polarity is considered being Active High. Even for the cases
+ * when _DSD() is involved (in the updated versions of ACPI)
+ * the GPIO CS polarity must be defined Active High to avoid
+ * ambiguity. That's why we use enable, that takes SPI_CS_HIGH
+ * into account.
+ */
+ if (has_acpi_companion(&spi->dev)) {
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++)
+ gpiod_set_value_cansleep(spi_get_csgpiod(spi, idx),
+ !enable);
+ } else {
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++)
+ /* Polarity handled by GPIO library */
+ gpiod_set_value_cansleep(spi_get_csgpiod(spi, idx),
+ activate);
+ }
+ }
+ /* Some SPI masters need both GPIO CS & slave_select */
+ if ((spi->controller->flags & SPI_MASTER_GPIO_SS) &&
+ spi->controller->set_cs)
+ spi->controller->set_cs(spi, !enable);
+ else if (spi->controller->set_cs)
+ spi->controller->set_cs(spi, !enable);
+ }
- if (spi_get_csgpiod(spi, 0)) {
- if (!(spi->mode & SPI_NO_CS)) {
- /*
- * Historically ACPI has no means of the GPIO polarity and
- * thus the SPISerialBus() resource defines it on the per-chip
- * basis. In order to avoid a chain of negations, the GPIO
- * polarity is considered being Active High. Even for the cases
- * when _DSD() is involved (in the updated versions of ACPI)
- * the GPIO CS polarity must be defined Active High to avoid
- * ambiguity. That's why we use enable, that takes SPI_CS_HIGH
- * into account.
- */
- if (has_acpi_companion(&spi->dev))
- gpiod_set_value_cansleep(spi_get_csgpiod(spi, 0), !enable);
- else
- /* Polarity handled by GPIO library */
- gpiod_set_value_cansleep(spi_get_csgpiod(spi, 0), activate);
+ for (idx = 0; idx < SPI_CS_CNT_MAX; idx++) {
+ if (spi_get_csgpiod(spi, idx) || !spi->controller->set_cs_timing) {
+ if (activate)
+ spi_delay_exec(&spi->cs_setup, NULL);
+ else
+ spi_delay_exec(&spi->cs_inactive, NULL);
+ }
}
- /* Some SPI masters need both GPIO CS & slave_select */
- if ((spi->controller->flags & SPI_MASTER_GPIO_SS) &&
- spi->controller->set_cs)
+ } else {
+ /*
+ * Avoid calling into the driver (or doing delays) if the chip select
+ * isn't actually changing from the last time this was called.
+ */
+ if (!force && ((enable && spi->controller->last_cs ==
+ spi_get_chipselect(spi, cs_num)) ||
+ (!enable && spi->controller->last_cs !=
+ spi_get_chipselect(spi, cs_num))) &&
+ (spi->controller->last_cs_mode_high ==
+ (spi->mode & SPI_CS_HIGH)))
+ return;
+
+ trace_spi_set_cs(spi, activate);
+
+ spi->controller->last_cs = enable ? spi_get_chipselect(spi, cs_num) : -1;
+ spi->controller->last_cs_mode_high = spi->mode & SPI_CS_HIGH;
+
+ if ((spi_get_csgpiod(spi, cs_num) || !spi->controller->set_cs_timing) && !activate)
+ spi_delay_exec(&spi->cs_hold, NULL);
+
+ if (spi->mode & SPI_CS_HIGH)
+ enable = !enable;
+
+ if (spi_get_csgpiod(spi, cs_num)) {
+ if (!(spi->mode & SPI_NO_CS)) {
+ /*
+ * Historically ACPI has no means of the GPIO polarity and
+ * thus the SPISerialBus() resource defines it on the per-chip
+ * basis. In order to avoid a chain of negations, the GPIO
+ * polarity is considered being Active High. Even for the cases
+ * when _DSD() is involved (in the updated versions of ACPI)
+ * the GPIO CS polarity must be defined Active High to avoid
+ * ambiguity. That's why we use enable, that takes SPI_CS_HIGH
+ * into account.
+ */
+ if (has_acpi_companion(&spi->dev))
+ gpiod_set_value_cansleep(spi_get_csgpiod(spi, cs_num),
+ !enable);
+ else
+ /* Polarity handled by GPIO library */
+ gpiod_set_value_cansleep(spi_get_csgpiod(spi, cs_num),
+ activate);
+ }
+ /* Some SPI masters need both GPIO CS & slave_select */
+ if ((spi->controller->flags & SPI_MASTER_GPIO_SS) &&
+ spi->controller->set_cs)
+ spi->controller->set_cs(spi, !enable);
+ } else if (spi->controller->set_cs) {
spi->controller->set_cs(spi, !enable);
- } else if (spi->controller->set_cs) {
- spi->controller->set_cs(spi, !enable);
- }
+ }
- if (spi_get_csgpiod(spi, 0) || !spi->controller->set_cs_timing) {
- if (activate)
- spi_delay_exec(&spi->cs_setup, NULL);
- else
- spi_delay_exec(&spi->cs_inactive, NULL);
+ if (spi_get_csgpiod(spi, cs_num) || !spi->controller->set_cs_timing) {
+ if (activate)
+ spi_delay_exec(&spi->cs_setup, NULL);
+ else
+ spi_delay_exec(&spi->cs_inactive, NULL);
+ }
}
}
@@ -2245,8 +2313,8 @@ static void of_spi_parse_dt_cs_delay(struct device_node *nc,
static int of_spi_parse_dt(struct spi_controller *ctlr, struct spi_device *spi,
struct device_node *nc)
{
- u32 value;
- int rc;
+ u32 value, cs[SPI_CS_CNT_MAX] = {0};
+ int rc, idx;
/* Mode (clock phase/polarity/etc.) */
if (of_property_read_bool(nc, "spi-cpha"))
@@ -2319,13 +2387,21 @@ static int of_spi_parse_dt(struct spi_controller *ctlr, struct spi_device *spi,
}
/* Device address */
- rc = of_property_read_u32(nc, "reg", &value);
- if (rc) {
+ rc = of_property_read_variable_u32_array(nc, "reg", &cs[0], 1,
+ SPI_CS_CNT_MAX);
+ if (rc < 0 || rc > ctlr->num_chipselect) {
dev_err(&ctlr->dev, "%pOF has no valid 'reg' property (%d)\n",
nc, rc);
return rc;
+ } else if ((of_property_read_bool(nc, "parallel-memories")) &&
+ (!ctlr->multi_cs_cap)) {
+ dev_err(&ctlr->dev, "SPI controller doesn't support multi CS\n");
+ return -EINVAL;
}
- spi_set_chipselect(spi, 0, value);
+ for (idx = 0; idx < rc; idx++)
+ spi_set_chipselect(spi, idx, cs[idx]);
+ /* By default set the spi->cs_index_mask as 1 */
+ spi->cs_index_mask = 0x01;
/* Device speed */
if (!of_property_read_u32(nc, "spi-max-frequency", &value))
@@ -3845,6 +3921,7 @@ static int __spi_validate(struct spi_device *spi, struct spi_message *message)
struct spi_controller *ctlr = spi->controller;
struct spi_transfer *xfer;
int w_size;
+ u32 cs_num = __ffs(spi->cs_index_mask);
if (list_empty(&message->transfers))
return -EINVAL;
@@ -3857,7 +3934,7 @@ static int __spi_validate(struct spi_device *spi, struct spi_message *message)
* cs_change is set for each transfer.
*/
if ((spi->mode & SPI_CS_WORD) && (!(ctlr->mode_bits & SPI_CS_WORD) ||
- spi_get_csgpiod(spi, 0))) {
+ spi_get_csgpiod(spi, cs_num))) {
size_t maxsize;
int ret;
@@ -19,6 +19,11 @@
#include <linux/acpi.h>
#include <linux/u64_stats_sync.h>
+/* Max no. of CS supported per spi device */
+#define SPI_CS_CNT_MAX 2
+
+/* chip select mask */
+#define SPI_PARALLEL_CS_MASK (BIT(0) | BIT(1))
struct dma_chan;
struct software_node;
struct ptp_system_timestamp;
@@ -166,6 +171,7 @@ extern void spi_transfer_cs_change_delay_exec(struct spi_message *msg,
* deasserted. If @cs_change_delay is used from @spi_transfer, then the
* two delays will be added up.
* @pcpu_statistics: statistics for the spi_device
+ * @cs_index_mask: Bit mask of the active chipselect(s) in the chipselect array
*
* A @spi_device is used to interchange data between an SPI slave
* (usually a discrete chip) and CPU memory.
@@ -181,7 +187,7 @@ struct spi_device {
struct spi_controller *controller;
struct spi_controller *master; /* Compatibility layer */
u32 max_speed_hz;
- u8 chip_select;
+ u8 chip_select[SPI_CS_CNT_MAX];
u8 bits_per_word;
bool rt;
#define SPI_NO_TX BIT(31) /* No transmit wire */
@@ -202,7 +208,7 @@ struct spi_device {
void *controller_data;
char modalias[SPI_NAME_SIZE];
const char *driver_override;
- struct gpio_desc *cs_gpiod; /* Chip select gpio desc */
+ struct gpio_desc *cs_gpiod[SPI_CS_CNT_MAX]; /* Chip select gpio desc */
struct spi_delay word_delay; /* Inter-word delay */
/* CS delays */
struct spi_delay cs_setup;
@@ -212,6 +218,13 @@ struct spi_device {
/* The statistics */
struct spi_statistics __percpu *pcpu_statistics;
+ /* Bit mask of the chipselect(s) that the driver need to use from
+ * the chipselect array.When the controller is capable to handle
+ * multiple chip selects & memories are connected in parallel
+ * then more than one bit need to be set in cs_index_mask.
+ */
+ u32 cs_index_mask : 2;
+
/*
* likely need more hooks for more protocol options affecting how
* the controller talks to each chip, like:
@@ -268,22 +281,22 @@ static inline void *spi_get_drvdata(struct spi_device *spi)
static inline u8 spi_get_chipselect(struct spi_device *spi, u8 idx)
{
- return spi->chip_select;
+ return spi->chip_select[idx];
}
static inline void spi_set_chipselect(struct spi_device *spi, u8 idx, u8 chipselect)
{
- spi->chip_select = chipselect;
+ spi->chip_select[idx] = chipselect;
}
static inline struct gpio_desc *spi_get_csgpiod(struct spi_device *spi, u8 idx)
{
- return spi->cs_gpiod;
+ return spi->cs_gpiod[idx];
}
static inline void spi_set_csgpiod(struct spi_device *spi, u8 idx, struct gpio_desc *csgpiod)
{
- spi->cs_gpiod = csgpiod;
+ spi->cs_gpiod[idx] = csgpiod;
}
/**
@@ -388,6 +401,8 @@ extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 ch
* @bus_lock_spinlock: spinlock for SPI bus locking
* @bus_lock_mutex: mutex for exclusion of multiple callers
* @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
+ * @multi_cs_cap: indicates that the SPI Controller can assert/de-assert
+ * more than one chip select at once.
* @setup: updates the device mode and clocking records used by a
* device's SPI controller; protocol code may call this. This
* must fail if an unrecognized or unsupported mode is requested.
@@ -585,6 +600,13 @@ struct spi_controller {
/* Flag indicating that the SPI bus is locked for exclusive use */
bool bus_lock_flag;
+ /*
+ * Flag indicating that the spi-controller has multi chip select
+ * capability and can assert/de-assert more than one chip select
+ * at once.
+ */
+ bool multi_cs_cap;
+
/* Setup mode and clock, etc (spi driver may call many times).
*
* IMPORTANT: this may be called when transfers to another