ish: Trim down the release branchstabilize-wristpin-14469.59.B-ishstabilize-voshyr-14637.B-ishstabilize-quickfix-14695.187.B-ishstabilize-quickfix-14695.124.B-ishstabilize-quickfix-14526.91.B-ishstabilize-14695.85.B-ishstabilize-14695.107.B-ishstabilize-14682.B-ishstabilize-14633.B-ishstabilize-14616.B-ishstabilize-14589.B-ishstabilize-14588.98.B-ishstabilize-14588.14.B-ishstabilize-14588.123.B-ishstabilize-14536.B-ishstabilize-14532.B-ishstabilize-14528.B-ishstabilize-14526.89.B-ishstabilize-14526.84.B-ishstabilize-14526.73.B-ishstabilize-14526.67.B-ishstabilize-14526.57.B-ishstabilize-14498.B-ishstabilize-14496.B-ishstabilize-14477.B-ishstabilize-14469.9.B-ishstabilize-14469.8.B-ishstabilize-14469.58.B-ishstabilize-14469.41.B-ishstabilize-14442.B-ishstabilize-14438.B-ishstabilize-14411.B-ishstabilize-14396.B-ishstabilize-14395.B-ishstabilize-14388.62.B-ishstabilize-14388.61.B-ishstabilize-14388.52.B-ishstabilize-14385.B-ishstabilize-14345.B-ishstabilize-14336.B-ishstabilize-14333.B-ishrelease-R99-14469.B-ishrelease-R98-14388.B-ishrelease-R102-14695.B-ishrelease-R101-14588.B-ishrelease-R100-14526.B-ishfirmware-cherry-14454.B-ishfirmware-brya-14505.B-ishfirmware-brya-14505.71.B-ishfactory-kukui-14374.B-ishfactory-guybrush-14600.B-ishfactory-cherry-14455.B-ishfactory-brya-14517.B-ish

In the interest of making long-term branch maintenance incur as little
technical debt on us as possible, we should not maintain any files on
the branch we are not actually using.

This has the added effect of making it extremely clear when merging CLs
from the main branch when changes have the possibility to affect us.

The follow-on CL adds a convenience script to actually pull updates from
the main branch and generate a CL for the update.

BUG=b:204206272
BRANCH=ish
TEST=make BOARD=arcada_ish && make BOARD=drallion_ish

Signed-off-by: Jack Rosenthal <jrosenth@chromium.org>
Change-Id: I17e4694c38219b5a0823e0a3e55a28d1348f4b18
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3262038
Reviewed-by: Jett Rink <jettrink@chromium.org>
Reviewed-by: Tom Hughes <tomhughes@chromium.org>

1 files changed, 0 insertions, 329 deletions

diff --git a/docs/core_runtime.md b/docs/core_runtime.md
deleted file mode 100644
index 4a45136234..0000000000
--- a/docs/core_runtime.md
+++ /dev/null
@@ -1,329 +0,0 @@
-# Chromium OS Embedded Controller Runtime
-
-## Design Principles
-
-1.  Never do at runtime what you can do at compile time The goal is saving flash
-    space and computations. Compile-time configuration until you really need to
-    switch at runtime.
-
-2.  Real-time: guarantee low latency (eg < 20 us) no interrupt disabling ...
-    bounded code in interrupt handlers.
-
-3.  Keep it simple: design for the subset of microcontroller we use targeted at
-    32-bit single core CPU for small systems : 4kB to 64kB data RAM, possibly
-    execute-in-place from flash.
-
-## Execution Contexts
-
-This is a pre-emptible runtime with static tasks. It has only 2 possible
-execution contexts:
-
--   the regular [tasks](#tasks)
--   the [interrupt handlers](#interrupts)
-
-The initial startup is an exception as described in the
-[dedicated paragraph](#startup).
-
-### Tasks
-
-The tasks are statically defined at compile-time. They are described for each
-*board* in the [board/$board/ec.tasklist](../board/host/ec.tasklist) file.
-
-They also have a static fixed priority implicitly defined at compile-time by
-their order in the [ec.tasklist](../board/host/ec.tasklist) file (the top-most
-one being the lowest priority aka *task* *1*). As a consequence, two different
-tasks cannot have the same priority.
-
-In order to store its context, each task has its own stack whose (*small*) size
-is defined at compile-time in the [ec.tasklist](../board/host/ec.tasklist) file.
-
-A task can normally be preempted at any time by either interrupts or higher
-priority tasks, see the [preemption section](#scheduling-and-preemption) for
-details and the [locking section](#locking-and-atomicity) for the few cases
-where you need to avoid it.
-
-### Interrupts
-
-The hardware interrupt requests are connected to the interruption handling *C*
-routines declared by the `DECLARE_IRQ` macros, through some chip/core specific
-mechanisms (e.g. depending on whether we have a vectored interrupt controller,
-slave interrupt controllers...)
-
-The interrupts can be nested (ie interrupted by a higher priority interrupt).
-All the interrupt vectors are assigned a priority as defined in their
-`DECLARE_IRQ` macro. The number of available priority level is
-architecture-specific (e.g. 4 on Cortex-M0, 8 on Cortex-M3/M4) and several
-interrupt handlers can have the same priority. An interrupt handler can only be
-interrupted by a handler having a priority **strictly** **greater** than its
-own.
-
-In most cases, the exceptions (e.g data/prefetch aborts, software interrupt) can
-be seen as interrupts with a priority strictly greater than all IRQ vectors. So
-they can interrupt any IRQ handler using the same nesting mechanism. All fatal
-exceptions should ultimately lead to a reboot.
-
-### Events
-
-Each task has a *pending* events bitmap[1] implemented as a 32-bit word. Several
-events are pre-defined for all tasks, the most significant bits on the 32-bit
-bitmap are reserved for them : the timer pending event on bit 31
-([see the corresponding section](#time)), the requested task wake (bit 29), the
-event to kick the waiters on a mutex (bit 30), along with a few hardware
-specific events. The 19 least significant bits are available for task-specific
-meanings.
-
-Those event bits are used in inter-task communication and scheduling mechanism,
-other tasks **and** interrupt handlers can atomically set them to request
-specific actions from the task. Therefore, the presence of pending events in a
-task bitmap has an impact on its scheduling as described in the
-[scheduling section](#scheduling-and-preemption). These requests are done using
-the `task_set_event()` and `task_wake()` primitives.
-
-The two typical use-cases are:
-
--   a task sends a message to another task (simply use some common memory
-    structures [see explanation](#single-address-space) and want it to process
-    it now.
--   a hardware IRQ occurred, and we need to do some long processing to respond
-    to it (e.g. an I2C transaction). The associated interrupt handler cannot do
-    it (for latency reason), so it will raise an event to ask a task to do it.
-
-The task code chooses to consume them (or a subset of them) when it's running
-through the `task_wait_event()` and `task_wait_event_mask()` primitives.
-
-### Scheduling and Preemption
-
-The system has a global bitmap[1] called `tasks_ready` containing one bit per
-task and indicating whether it is *ready* *to* *run* (ie want/need to be
-scheduled). The task ready bit can only be cleared when it's calling itself one
-of the functions explicitly triggering a re-scheduling (e.g. `task_wait_event()`
-or `task_set_event()`) **and** it has no pending event. The task ready bit is
-set by any task or interrupt handler setting an event bit for the task (ie
-`task_set_event()`).
-
-The scheduling is based on (and *only* on) the `tasks_ready` bitmap (which is
-derived from all the events bitmap of the tasks as explained above).
-
-Then, the scheduling policy to find which task should run is just finding the
-most significant bit set in the tasks_ready bitmap and schedule the
-corresponding task.
-
-Important note: the re-scheduling happens **only** when we are exiting the
-interrupt context. It is done in a non-preemptible context (likely with the
-highest priority). Indeed, a re-scheduling is actually needed only when the
-highest priority task ready has changed. There are 3 distinct cases where this
-can happen:
-
--   an interrupt handler sets a new event for a task. In this case,
-    `task_set_event` will detect that it is executed in interrupt context and
-    record in the `need_resched_or_profiling` variable that it might need to
-    re-schedule at interrupt return. When the current interrupt is going to
-    return, it will see this bit and decide to take the slow path making a new
-    scheduling decision and eventually a context switch instead of the fast path
-    returning to the interrupt task.
--   a task sets an event on another task. The runtime will trigger a software
-    interrupt to force a re-scheduling at its exit.
--   the running task voluntarily relinquish its current execution rights by
-    calling `task_wait_event()` or a similar function. This will call the
-    software interrupt similarly to the previous case.
-
-On the re-scheduling path, if the highest-priority ready task is not matching
-the currently running one, it will perform a context-switch by saving all the
-processor registers on the current task stack, switch the stack pointer to the
-newly scheduled task, and restore the registers from the previously saved
-context from there.
-
-### Hooks and Deferred Functions
-
-The lowest priority task (ie Task 1, aka TASK_ID_HOOKS) is reserved to execute
-repetitive actions and future actions deferred in time without blocking the
-current task or creating a dedicated task (whose stack memory allocation would
-be wasting precious RAM).
-
-The HOOKS task has a list of deferred functions and their next deadline. Every
-time it is waken up, it runs through the list and calls the ones whose deadline
-is expired. Before going back to sleep, it arms a timer to the closest deadline.
-The deferred functions can be created using the `DECLARED_DEFERRED()` macro.
-Similarly, the HOOK_SECOND and HOOK_TICK hooks are called periodically by the
-HOOKS task loop (the *tick* duration is platform-defined and shorter than the
-second).
-
-Note: be specially careful about priority inversions when accessing resources
-protected by a mutex (e.g. a shared I2C controller) in a deferred function.
-Indeed being the lowest priority task, it might be de-scheduled for long time
-and starve higher priority tasks trying to access the resource given there is no
-priority boosting implemented for this case. Also, be careful about long delays
-(> x 100us) in hook or deferred function handlers, since those will starve other
-hooks of execution time. It is better to implement a state machine where you set
-up a subsequent call to a deferred function than have a long delay in your
-handler.
-
-### Watchdog
-
-The system is always protected against misbehaving tasks and interrupt handlers
-by a hardware watchdog rebooting the CPU when it is not attended.
-
-The watchdog is petted in the HOOKS task, typically by declaring a HOOK_TICK
-doing it as regular intervals. Given this is the lowest priority task, this
-guarantees that all tasks are getting some run time during the watchdog period.
-
-Note: that's also why one should not sprinkle its code with `watchdog_reload()`
-to paper over long-running routine issues.
-
-To help debug bad sequences triggering watchdog reboots, most platforms
-implement a warning mechanism defined under `CONFIG_WATCHDOG_HELP`. It's a timer
-firing at the middle of the watchdog period if it hasn't been petted by then,
-and dumping on the console the current state of the execution mainly to help
-find a stuck task or handler. The normal execution is resumed though after this
-alert.
-
-### Startup
-
-The startup sequence goes through the following steps:
-
--   the assembly entry routine clears the .bss (uninitialized data), copies the
-    initialized data (and optionally the code if we are not executing from
-    flash), sets a stack pointer.
--   we can jump to the `main()` C routine at this point.
--   then we go through the hardware pre-init (before we have all the clocks to
-    run the peripherals normal) and init routines, in this rough order: memory
-    protection if any, gpios in their default state, prepare the interrupt
-    controller, set the clocks, then timers, enable interrupts, init the debug
-    UART and the watchdog.
--   finally, start tasks.
-
-For the tasks startup, initially only the HOOKS task is marked as ready, so it
-is the first to start and can call all the HOOK_INIT handlers performing
-initializations before actually executing any real task code. Then all tasks are
-marked as ready, and the highest priority one is given the control.
-
-During all the startup sequence until the control is given the first task, we
-are using a special stack called 'system stack' which will be later re-used as
-the interrupts and exception stack.
-
-To prepare the first context switch, the code in `task_pre_init()` is stuffing
-all the tasks stacks with a *fake* saved context whose program counter contains
-the task start address, and the stack pointer is pointing to its reserved stack
-space.
-
-### Locking and Atomicity
-
-The two main concurrency primitives are lightweight atomic variables and heavier
-mutexes.
-
-The atomic variables are 32-bit integers (which can usually be loaded/stored
-atomically on the architecture we are supporting). The `atomic.h` headers
-include primitives to do atomically various bit and arithmetic operations using
-either load-linked/load-exclusive, store-conditional/store-exclusive or simple
-depending on what is available.
-
-The mutexes are actually statically allocated binary semaphores. In case of
-contention, they will make the waiting task sleep (removing its ready bit) and
-use the [event mechanism](#events) to wake-up the other waiters on unlocking.
-
-Note: the mutexes are NOT triggering any priority boosting to avoid the priority
-inversion phenomenon.
-
-Given the runtime is running on single core CPU, spinlocks would be equivalent
-to masking interrupts with `interrupt_disable()` spinlocks, but it's strongly
-discouraged to avoid harming the real-time characteristics of the runtime.
-
-## Time
-
-### Time Keeping
-
-In the runtime, the time is accounted everywhere using a **64-bit**
-**microsecond** count since the microcontroller **cold** **boot**.
-
-Note: The runtime has no notion of wall-time/date, even though a few platforms
-have an RTC inside the microcontroller.
-
-These microsecond timestamps are implemented in the code using the `timestamp_t`
-type, and the current timestamp is returned by the `get_time()` function.
-
-The time-keeping is preferably implemented using a 32-bit hardware free running
-counter at 1Mhz plus a 32-bit word in memory keeping track of the high word of
-the 64-bit absolute time. This word is incremented by the 32-bit timer rollback
-interrupt.
-
-Note: as a consequence of this implementation, when the 64-bit timestamp is read
-in interrupt context in a handler having a higher priority than the timer IRQ
-(which is somewhat rare), the high 32-bit word might be incoherent (off by one).
-
-### Timer Event
-
-The runtime offers *one* (and only one) timer per task. All the task timers are
-multiplexed on a single hardware timer. (can be just a *match* *interrupt* on
-the free running counter mentioned in the [previous paragraph](#time-keeping))
-Every time a timer is armed or expired, the runtime finds the task timer having
-the closest deadline and programs it in the hardware to get an interrupt. At the
-same time, it sets the TASK_EVENT_TIMER event in all tasks whose timer deadline
-has expired. The next deadline is computed in interrupt context.
-
-Note: given each task has a **single** timer which is also used to wake-up the
-task when `task_wait_event()` is called with a timeout, one needs to be careful
-when using directly the `timer_arm()` function because there is an eventuality
-that this timer is still running on the next `task_wait_event()` call, the call
-will fail due to the lack of available timer.
-
-## Memory
-
-### Single Address Space
-
-There is no memory isolation between tasks (ie they all live in the same address
-space). Some architectures implement memory protection mechanism albeit only to
-differentiate executable area (eg `.code`) from writable area (eg `.bss` or
-`.data`) as there is a **single** **privilege** level for all execution
-contexts.
-
-As all the memory is implicitly shared between the task, the inter-task
-communication can be done by simply writing the data structures in memory and
-using events to wake the other task (given we properly thought the concurrent
-accesses on those structures).
-
-### Heap
-
-The data structure should be statically allocated at compile time.
-
-Note: there is no dynamic allocator available (e.g. `malloc()`), not due to
-impossibility to create one but to avoid the negative side effects of having
-one: ie poor/unpredictable real-time behavior and possible leaks leading to a
-long-tail of failures.
-
--   TODO: talk about shared memory
--   TODO: where/how we store *panic* *memory* and *sysjump* *parameters*.
-
-### Stacks
-
-Each task has its own stack, in addition there is a system stack used for
-startup and interrupts/exceptions.
-
-Note 1: Each task stack is relatively small (e.g. 512 bytes), so one needs to be
-careful about stack usage when implementing features.
-
-Note 2: At the same time, the total size of RAM used by stacks is a big chunk of
-the total RAM consumption, so their sizes need to be carefully tuned. (please
-refer to the [debugging paragraph](#debugging) for additional input on this
-topic.
-
-## Firmware Code Organization and Multiple Copies
-
--   TODO: Details the classical RO / RW partitions and how we sysjump.
-
-## Power Management
-
--   TODO: talk about the idle task + WFI (note: interrupts are disabled!)
--   TODO: more about low power idle and the sleep-disable bitmap
--   TODO: adjusting the microsecond timer at wake-up
-
-## Debugging
-
--   TODO: our main tool: serial console ... (but non-blocking / discard
-    overflow, cflush DO/DONT)
--   TODO: else JTAG stop and go: careful with watchdog and timer
--   TODO: panics and software panics
--   TODO: stack size tuning and canarying
-
--   TODO: Address the rest of the comments from https://crrev.com/c/445941
-
-\[1]: bitmap: array of bits.