Summary:
- This commit fixes global IRQ control logic
- In previous implementation, g_cpu_irqset for a remote CPU was
set in sched_add_readytorun(), sched_remove_readytorun() and
up_schedule_sigaction()
- In this implementation, they are removed.
- Instead, in the pause handler, call enter_critical_setion()
which will call up_cpu_paused() then acquire g_cpu_irqlock
- So if a new task with irqcount > 1 restarts on the remote CPU,
the CPU will only hold a critical section. Thus, the issue such as
'POSSIBLE FOR TWO CPUs TO HOLD A CRITICAL SECTION' could be resolved.
- Fix nxsched_resume_scheduler() so that it does not call spin_clrbit()
if a CPU does not hold a g_cpu_irqset
- Fix nxtask_exit() so that it acquires g_cpu_irqlock
- Update TODO
Impact:
- All SMP implementations
Testing:
- Tested with smp, ostest with the following configurations
- Tested with spresense:wifi_smp (NCPUS=2,4)
- Tested with sabre-6quad:smp (QEMU, dev board)
- Tested with maix-bit:smp (QEMU)
- Tested with esp32-core:smp (QEMU)
- Tested with lc823450-xgevk:rndis
Signed-off-by: Masayuki Ishikawa <Masayuki.Ishikawa@jp.sony.com>
Summary:
- Apply the same logic added to cxd56_cpupause.c
Impact:
- SMP only
Testing:
- Tested with maix-bit:smp (QEMU)
- Run smp and ostest
Signed-off-by: Masayuki Ishikawa <Masayuki.Ishikawa@jp.sony.com>
So that it matches what the toolchain expects.
spacetanuki% riscv64-unknown-elf-gcc --version
riscv64-unknown-elf-gcc (SiFive GCC 8.3.0-2019.08.0) 8.3.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
spacetanuki% riscv64-unknown-elf-gcc -dM -E - < /dev/null | grep UINT64_TYPE
#define __UINT64_TYPE__ long unsigned int
spacetanuki%
Summary:
- Apply the same fix for Arm SMP
Impact:
- Affects SMP only
Testing:
- Tested with maix-bit:smp (qemu)
Signed-off-by: Masayuki Ishikawa <Masayuki.Ishikawa@jp.sony.com>
When executing an MRET instruction, MIE is set to MPIE.
In order to branch to up_sigdeliver() with interrupts disabled,
we need to change MPIE, not MIE.
When executing an MRET instruction, MIE is set to MPIE.
In order to branch to up_sigdeliver() with interrupts disabled,
we need to change MPIE, not MIE.
and remove the special handling in the stack dump
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: Ia1ef9a427bd4c7f6cee9838d0445f29cfaca3998
EXTRAFLAGS is already applied to *FLAGS in board's Make.defs (and
it applies to whole build, not just arch-code). EXTRAFLAGS is passed
around each make call to the complete build.
KDEFINE is already added to EXTRAFLAGS in main Makefile so no need
to add it again in arch-level Makefile
1.Reduce the default size of task_group_s(~512B each task)
2.Scale better between simple and complex application
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: Ia872137504fddcf64d89c48d6f0593d76d582710
Summary:
- ARCH_GLOBAL_IRQDISABLE was initially introduced for LC823450 SMP
- At that time, i.MX6 (quad Cortex-A9) did not use this config
- However, this option is now used for all CPUs which support SMP
- So it's good timing for refactoring the code
Impact:
- Should have no impact because the logic is the same for SMP
Testing:
- Tested with board: spresense:smp, spresense:wifi_smp
- Tested with qemu: esp32-core:smp, maix-bit:smp, sabre-6quad:smp
- Build only: lc823450-xgevk:rndis, sam4cmp-db:nsh
Signed-off-by: Masayuki Ishikawa <Masayuki.Ishikawa@jp.sony.com>
PR #1450 broke the Cygwin build. Refer to Issue #1672.
The use of of logic like:
EXTRA_LIBPATHS += -L "${dir ${shell $(CC) $(ARCHCPUFLAGS) --print-file-name=libgcc.a}}"
fails when the Toolchain $(CC) is a native Windows toolchain. That is because the returned path is a Windows-style patch which cannot be handled by the make 'dir' command. Commit 4910d43ab0 reorganized a lot of definitions and replaced the correct code with the use of the limit make 'dir' command. The original code used the Bash dirname command which does not suffer from this limitation; it can handle both POSIX and Windows paths.
This was verified using the stm32f4discover:nsh toolchain with the Windows native ARM Embedded toolchain. That toolchain returns:
arm-none-eabi-gcc --print-file-name=libgcc.a
c:/program files (x86)/gnu tools arm embedded/9 2019-q4-major/bin/../lib/gcc/arm-none-eabi/9.2.1/libgcc.a
because nx_task_idle doesn't call sched_note_start. To avoid the
same error happen again in the furture, nx_task_idle is removed.
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Make.dep file should be updated by .config changed after first make.
There are 2 cases affected for this problem:
1) Add source files by config symbol
2) Include header files in #ifdef directive
These 2 cases may not be included in Make.dep and this may prevent the
differential build from working correctly.
1.It make sense to let Toolchain.defs give the default value
2.The board can still change if the default isn't suitable
3.Avoid the same definition spread more than 200 Make.defs
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: Ic2649f1c7689bcf59c105ca8db61cad45b6e0e64
since exit will be only callable from userspace and change
the 1st argument from "const uint8_t *" to "const char *"
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: I86487d57210ab63109148232da71dbc4d60a563b
ASAN trace:
...
==32087==ERROR: AddressSanitizer: heap-buffer-overflow on address 0xf4502120 at pc 0x56673ca3 bp 0xff9b6a08 sp 0xff9b69f8
WRITE of size 1 at 0xf4502120 thread T0
#0 0x56673ca2 in strcpy string/lib_strcpy.c:64
0xf4502120 is located 0 bytes to the right of 8224-byte region [0xf4500100,0xf4502120)
allocated by thread T0 here:
#0 0xf7a60f54 in malloc (/usr/lib32/libasan.so.4+0xe5f54)
#1 0x5667725d in up_create_stack sim/up_createstack.c:135
#2 0x56657ed8 in nxthread_create task/task_create.c:125
#3 0x566580bb in kthread_create task/task_create.c:297
#4 0x5665935f in work_start_highpri wqueue/kwork_hpthread.c:149
#5 0x56656f31 in nx_workqueues init/nx_bringup.c:181
#6 0x56656fc6 in nx_bringup init/nx_bringup.c:436
#7 0x56656e95 in nx_start init/nx_start.c:809
#8 0x566548d4 in main sim/up_head.c:95
#9 0xf763ae80 in __libc_start_main (/lib/i386-linux-gnu/libc.so.6+0x18e80)
CALLSTACK:
#8 0xf79de7a5 in __asan_report_store1 () from /usr/lib32/libasan.so.4
#9 0x565fd4d7 in strcpy (dest=0xf4a02121 "", src=0xf5c00895 "k") at string/lib_strcpy.c:64
#10 0x565e4eb2 in nxtask_setup_stackargs (tcb=0xf5c00810, argv=0x0) at task/task_setup.c:570
#11 0x565e50ff in nxtask_setup_arguments (tcb=0xf5c00810, name=0x5679e580 "hpwork", argv=0x0) at task/task_setup.c:714
#12 0x565e414e in nxthread_create (name=0x5679e580 "hpwork", ttype=2 '\002', priority=224, stack=0x0, stack_size=8192, entry=0x565e54e1 <work_hpthread>, argv=0x0) at task/task_create.c:143
#13 0x565e42e3 in kthread_create (name=0x5679e580 "hpwork", priority=224, stack_size=8192, entry=0x565e54e1 <work_hpthread>, argv=0x0) at task/task_create.c:297
#14 0x565e5557 in work_start_highpri () at wqueue/kwork_hpthread.c:149
#15 0x565e3e32 in nx_workqueues () at init/nx_bringup.c:181
#16 0x565e3ec7 in nx_bringup () at init/nx_bringup.c:436
#17 0x565e3d96 in nx_start () at init/nx_start.c:809
#18 0x565e3195 in main (argc=1, argv=0xffe6b954, envp=0xffe6b95c) at sim/up_head.c:95
Change-Id: I096f7952aae67d055daa737e967242eb217ef8ac
Signed-off-by: chao.an <anchao@xiaomi.com>
like other related macro(e.g. INTMAX_MIN, INTMAX_MAX...)
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: I8863599960b1a9b1c22ae9c35735a379a4c745b0
utilize the call inside nxtask_exit instead, also move
nxsched_suspend_scheduler to nxtask_exit for symmetry
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
Change-Id: I219fc15faf0026e452b0db3906aa40b40ac677f3
-Move task_init() and task_activate() prototypes from include/sched.h to include/nuttx/sched.h. These are internal OS functions and should not be exposed to the user.
-Remove references to task_init() and task_activate() from the User Manual.
-Rename task_init() to nxtask_init() since since it is an OS internal function
-Rename task_activate() to nxtask_activate since it is an OS internal function
remove the TLS alignment check
Regression by:
--------------------------------------------------------
commit a6da3c2cb6
Author: Ouss4 <abdelatif.guettouche@gmail.com>
Date: Thu May 7 18:50:07 2020 +0100
arch/*/*_checkstack.c: Get aligned address only when
CONFIG_TLS_ALIGNED is enabled.
--------------------------------------------------------
commit c2244a2382
Author: Gregory Nutt <gnutt@nuttx.org>
Date: Thu May 7 09:46:47 2020 -0600
Remove CONFIG_TLS
A first step in implementing the user-space error is
force TLS to be enabled at all times. It is no longer optional
Signed-off-by: chao.an <anchao@xiaomi.com>
- Remove per-thread errno from the TCB structure (pterrno)
- Remove get_errno() and set_errno() as functions. The macros are still available as stubs and will be needed in the future if we need to access the errno from a different address environment (KERNEL mode).
- Add errno value to the tls_info_s structure definitions
- Move sched/errno to libs/libc/errno. Replace old TCB access to the errno with TLS access to the errno.
Mac OS X was renamed to macOS at some point. Update references to
OSX, OS X, Mac OS X, Mac OSX, and other permutations, to macOS,
in README files and in comments of other files.
So call 'make EXTRAFLAGS=-Wno-cpp' could suppress the warnings with pre-processor
directive #warning in GCC.
Change-Id: Iaa618238924c9969bf91db22117b39e6d2fc9bb6
Signed-off-by: liuhaitao <liuhaitao@xiaomi.com>
There are cases that USE_SERIALDRIVER is defined but USE_EARLYSERIALINIT not defined in some configs. So use ifdef USE_EARLYSERIALINIT to include up_earlyserialinit anyway.
An error was introduced from:
commit f982ee43db
Author: Xiang Xiao <xiaoxiang@xiaomi.com>
Date: Tue Feb 18 09:55:04 2020 +0800
drivers/serial: Remove the lowconsole driver
Replace with the syslog console driver which has more capability than lowconsole
And remove syslog_init_e because all initialization is later now and we don't
distinguish the initialition phase anymore after ramlog don't need special
initialize.
Because we can get the same function by CONSOLE_SYSLOG/syslog_console_init.
BTW, it isn't a good choice to use g_ramlogfops as /dev/console since nsh
will read back what it send out which will surprise most people.
it doesn't make sense that iob initialization is in up_initialize
but other memory components initialization is called in nx_start
Change-Id: Id43aeaa995f340c5943f59a0067a483ff3ac34a2
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
To ensure size_t same as toolchain definition in the first place and rename CXX_NEWLONG to ARCH_SIZET_LONG. The change also check whether __SIZE_TYPE__ exist before CONFIG_ARCH_SIZET_LONG so our definition can align with toolchain(gcc/clang) definition automatically.
Call xxx_timer_initialize from clock subsystem to make timer ready for use as soon as possiblei and revert the workaround:
commit 0863e771a9
Author: Gregory Nutt <gnutt@nuttx.org>
Date: Fri Apr 26 07:24:57 2019 -0600
Revert "sched/clock/clock_initialize.c: clock_inittime() needs to be done with CONFIG_SCHED_TICKLESS and clock_initialize should skip clock_inittime() for external RTC case since the RTC isn't ready yet."
This reverts commit 2bc709d4b9.
Commit 2bc709d4b9 was intended to handle the case where up_timer_gettime may not start from zero case. However, this change has the side-effect of breaking every implementation of tickless mode: After this change the tickless timer structures are used before they are initialized in clock_inittime(). Initialization happens later when up_initialize is called() when arm_timer_initialize().
Since the tickless mode timer is very special, one solution might be to
1. Rename xxx_timer_initialize to up_timer_initialize
2 Move up_timer_initialize to include/nuttx/arch.h
3. Call it from clock subsystem instead up_initialize
Basically, this change make timer initialization almost same as rtc initialization(up_rtc_initialize).
For now, however, we just need to revert the change.
* include: Introduce elf64.h and elf.h
Added elf64.h for 64bit ELF support and moved common definitions
from elf32.h to elf.h. Also introduced Elf_xxx to be used in
common libraries such as binfmt.
* binfmt, include, modlib, module: Add support for ELF64
Elf_xxx must be used instead of Elf32_xxx to support ELF64.
To use ELF64, CONFIG_ELF_64BIT must be enabled.
* binfmt, modlib: Add support for relocate address
* arch: risc-v: Add include/elf.h
* libs: machine: Add risc-v related files.
NOTE: Currently only supports ELF64
* boards: maix-bit: Add elf and posix_spawn configurations
* boards: maix-bit: Add support for module configuration
Author: Alan Carvalho de Assis <acassis@gmail.com>
Run nxstyle against .c and .h files and fix it
Author: Juha Niskanen <juha.niskanen@haltian.com>
Fix typos and some incorrect comments
* arch: risc-v: Remove unused typedef for irqstate_t
NOTE: irqstate_t is defined in arch/risc-v/include/types.h
* arch: risc-v: Add typedef irqstate_t for __LP64__
* arch: risc-v: Add SMP support to K210 (RV64GC) processor
* boards: maxi-bit: Update READMEs and add smp/defconfig
In previous commit, mstatus.mie was set when creating a new task
but this change was incorrect and had a side effect such that
a machine interrupt would be enabled just before returning from
interrupt handling routine to switch context.
Also, mstatus.mpp is set to machine mode in up_get_newintctx()
instead of fe310_dispatch_irq().
* Simplify EINTR/ECANCEL error handling
1. Add semaphore uninterruptible wait function
2 .Replace semaphore wait loop with a single uninterruptible wait
3. Replace all sem_xxx to nxsem_xxx
* Unify the void cast usage
1. Remove void cast for function because many place ignore the returned value witout cast
2. Replace void cast for variable with UNUSED macro
Author: Gregory Nutt <gnutt@nuttx.org>
Run all .c and .h modified in PR through nxstyle.
Author: Masayuki Ishikawa <masayuki.ishikawa@gmail.com>
feature k210 (#16)
* arch: risc-v: Add support for __LP64__ to types.h
* arch: risc-v: Add support for RV64GC to common files
* arch: risc-v: Add support for Kendryte K210 processor (RV64GC)
* boards: risk-v: Add support for Sipeed Maix Bit with K210
* tools: Add support for Kendryte K210 processor
Fix fe310 signal handling
* arch: fe310: Disable all interrupts in mie at __start
* arch: fe310: Fix up_irq_enable() to set external interrupt only
* arch: fe310: Fix up_schedule_sigaction() to save REG_INT_CTX
* boards: hifive1-revb: Adjust stack size to reduce runtime memory
Approved-by: Gregory Nutt <gnutt@nuttx.org>
Sparkfun RED-V Things Plus
* board: hifive1-revb: Update README-qemu.txt
* arch: fe310: Works with SparkFun RED-V Things Plus
Should work with HiFive1 Rev.B but not tested yet.
* boards: hifive1-revb: Works with SparkFun RED-V Things Plus
Should work with HiFive1 Rev.B but not tested yet.
Approved-by: Alan Carvalho de Assis <acassis@gmail.com>
Approved-by: Gregory Nutt <gnutt@nuttx.org>
riscv updates
* arch: risc-v: Remove up_dumpstate.c because the file had been merged into up_assert.c
* boards: gapuino: Modify Makefile which conforms to NuttX standards
* boards: nr5m100-nexys4: Modify Makefile which conforms to NuttX standards
Approved-by: Gregory Nutt <gnutt@nuttx.org>
HiFive1 with qemu
* arch: risc-v: Add include/.gitignore
* arch: risc-v: Add src/.gitignore
* arch: risc-v: Remove uncommon function prototypes in include/irq.h
* arch: risc-v: Add missing symbols and function prototypes in src/common/up_internal.h
* arch: risc-v: Add src/common/up_modifyreg32.c
* arch: risc-v: Enable include Make.dep in src/Makefile
* arch: risc-v: Fix stack coloration in common/up_createstack.c
* arch: risc-v: Add common/up_puts.c
* arch: risc-v: Add common/up_checkstack.c
* arch: rv32im: Move all logics from up_dumpstate.c to up_assert.c
This change is same as other architectures like arm/src/armv7-m
* arch: Select ARCH_HAVE_STACKCHECK for RISC-V in Kconfig
* arch: risc-v: Add SiFive fe310 processor
NOTE: Currently only tested with qemu
* boards: hifive1-revb: Add SiFive hifive1-revb board
NOTE: Currently only tested with qemu
* tools: Add fe310 processor to configure.sh
Approved-by: Alan Carvalho de Assis <acassis@gmail.com>
Approved-by: Gregory Nutt <gnutt@nuttx.org>
libs/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
syscall/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
wireless/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
Documentation/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
include/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
drivers/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
sched/: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
configs: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
arch/xtensa: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
arch/z80: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
arch/x86: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
arch/renesas and arch/risc-v: Remove references to CONFIG_DISABLE_SIGNALS. Signals can no longer be disabled.
arch/or1k: Remove all references to CONFIG_DISABLE_SIGNALS. Signals are always enabled.
arch/misoc: Remove all references to CONFIG_DISABLE_SIGNALS. Signals are always enabled.
arch/mips: Remove all references to CONFIG_DISABLE_SIGNALS. Signals are always enabled.
arch/avr: Remove all references to CONFIG_DISABLE_SIGNALS. Signals are always enabled.
arch/arm: Remove all references to CONFIG_DISABLE_SIGNALS. Signals are always enabled.
Squashed commit of the following:
configs/: The few configurations that formerly set CONFIG_NFILE_DESCRIPTORS=0 should not default, rather they should set the number of descriptors to 3.
fs/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
tools/: Tools updates for changes to usage of CONFIG_NFILE_DESCRIPTORS.
syscall/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
libs/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
include/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
drivers/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
Documentation/: Remove all references to CONFIG_NFILE_DESCRIPTORS == 0
binfmt/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
arch/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
net/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
sched/: Remove all conditional logic based on CONFIG_NFILE_DESCRIPTORS == 0
sched/Kconfig: CONFIG_NFILE_DESCRIPTORS may no longer to set to a value less than 3
configs/: Remove all settings for CONFIG_NFILE_DESCRIPTORS < 3
sched/init/nx_bringup.c: Fix a naming collision.
sched/init: Rename os_start() to nx_start()
sched/init: Rename os_smp* to nx_smp*
sched/init: Rename os_bringup to nx_bringup
sched/init: rename all internal static functions to begin with nx_ vs os_
Squashed commit of the following:
Trivial, cosmetic
sched/, arch/, and include: Rename task_vforkstart() as nxtask_vforkstart()
sched/, arch/, and include: Rename task_vforkabort() as nxtask_vforkabort()
sched/, arch/, and include: Rename task_vforksetup() as nxtask_vfork_setup()
sched/: Rename notify_cancellation() as nxnotify_cancellation()
sched/: Rename task_recover() to nxtask_recover()
sched/task, sched/pthread/, Documentation/: Rename task_argsetup() and task_terminate() to nxtask_argsetup() and nxtask_terminate(), respectively.
sched/task: Rename task_schedsetup() to nxtask_schedsetup()
sched/ (plus some binfmt/, include/, and arch/): Rename task_start() and task_starthook() to nxtask_start() and nxtask_starthook().
arch/ and sched/: Rename task_exit() and task_exithook() to nxtask_exit() and nxtask_exithook(), respectively.
sched/task: Rename all internal, static, functions to begin with the nx prefix.
Squashed commit of the following:
Author: Gregory Nutt <gnutt@nuttx.org>
Completes review of configs/gapuino.
arch/risc-v/include/gap8/chip.h: Replace the moved chip.h header file with a dummy chip.h header file just to keep the system happy.
Move include/gap8/chip.h to src/gap8/chip.h. Internal details should not be exposed outside of arch/ and configs/. Review all headers files in src/gap8
Review of arch/risc-v/include.
Author: hhuysqt <hyq9606@126.com>
corrected author and email
Add app initialization, add signal support, cleanup irq context and configs
fix some warnings
gapuino initial port
GAP8 initial port
Signal handlers maybe run with interrupts enabled or disabled, depending on how the task the received the signal was blocked. (i.e.: If sem_wait() is called, then we disable interrupts, then block the currently running task). This could be dangerous, because user code would be running with interrupts disabled.
This change forces interrupts to be enabled in up_sigdeliver() before executing the signal handler calling up_irq_enable() explicitly. This is safe because, when we return to normal execution, interrupts will be restored to their previous state when the signal handler returns.
fs/userfs: This completes coding of the UserFS client and of the UserFS feature in general. This feature is being merged to main now because I believe it is innocuous. It is, however, untesed. The next step will be to develop a test case to verify the feature.
fs/userfs: Completes the request logic for the UserFS client. Still need the logic that receives the responses.
fs/userfs: Completes coding for most of the server side of the user filesystem logic.
fs/userfs: Big design changes, simplications. Use Unix domain local sockets instead of message queues. Easier to transfer big data in local sockets than message queues. Remove character drvier 'factory' it is not necessary.
fs/userfs: Minor reparitioning; volume private info does not need to be held on the OS client side.
libc/userfs: Add some of the server side logic.
fs/userfs: Add some UserFS initialization logic.
fs/userfs: Add frame work for the UserFS proxy. Remove all references to a block driver. There is no block dricer... what was I thinking?
fs/userfs: Add some initialization of the character driver, 'factory' device.
fs/userfs: Rename from fusefs to userfs to that we don't stomp on someone else's cool name.
Add a header file describing the fusefs interface.
Provide a user defined callback context for irq's, such that when
registering a callback users can provide a pointer that will get
passed back when the isr is called.
