spi_bus_lock_touch() function

Handle to the device to operate the registers

Get the device ID of a lock. The callers should allocate CS pins according to this ID.

Detach a device from its bus and free the resources used

Release the bus acquired. Will pass the acquiring processor to other blocked processors (tasks or ISR), and cause them to be unblocked or invoked. The acquiring device may also become NULL if no device is asking for acquiring. In this case, the BG may be invoked if there is any BG requests. If the new acquiring device has BG requests, the BG will be invoked before the task is resumed later after the BG finishes all requests of the new acquiring device. Otherwise the task of the new acquiring device will be resumed immediately.

Acquiring service

Attach a device onto an SPI bus lock. The returning handle is used to perform following requests for the attached device.

Wait until the ISR has finished all the BG operations for the acquiring device. If any `spi_bus_lock_bg_request` for this device has been called after `spi_bus_lock_acquire_start`, this function must be called before any operation in the task.

Find the next acquiring processor according to the status. Will directly change the acquiring device if new one found. Cases: - BG should still be the acquiring processor (Return false): 1. Acquiring device has active BG bits: out_desired_dev = new acquiring device 2. No acquiring device, but BG active: out_desired_dev = randomly pick one device with active BG bits - BG should yield to the task (Return true): 3. Acquiring device has no active BG bits: out_desired_dev = new acquiring device 4. No acquiring device while no active BG bits: out_desired_dev=NULL Acquiring device task need to be resumed only when case 3. This scheduling can happen in either task or ISR, so `in_isr` or `bg_active` not touched.

BG (Background, for ISR or cache) service ******************** Call by a device to request a BG operation. Depending on the bus lock state, the BG operations may be resumed by this call, or pending until BG operations allowed. Cleared by `spi_bus_lock_bg_clear_req` in the BG.

Clear the pending BG operation request of a device after served. Must be called when the ISR is acting as the acquiring processor.

Check whether there is device asking for the acquiring device, and the desired device for the next operation is also recommended.

Check if the device has BG requests. Must be called when the ISR is acting as the acquiring processor.

Initialize OS-level functions for a specific chip.

Deinitialize OS-level functions

Schedule service The modification to the status bits may cause rotating of the acquiring processor. It also have effects to `acquired_dev` (the acquiring device), `in_isr` (HW used in BG), and `acq_dev_bg_active` (wait_bg_end can be skipped) members of the lock structure. Most of them should be atomic, and special attention should be paid to the operation sequence.

Get the parent bus lock of the device