DEV_NUM_MAX macro

SPI Bus Lock for arbitration among SPI master (intr, polling) trans, SPI flash operations and flash/psram cache access. NON-PUBLIC API. Don't use it directly in applications. There is the main lock corresponding to an SPI bus, of which several devices (holding child locks) attaching to it. Each of the device is STRONGLY RECOMMENDED to be used in only one task to avoid concurrency issues. Terms: - BG operations (BackGround operations) means some transaction that will not immediately / explicitly be sent in the task. It can be some cache access, or interrupt transactions. - Operation: usage of the bus, for example, do SPI transactions. - Acquiring processor: the task or the ISR that is allowed to use the bus. No operations will be performed if there is no acquiring processor. A processor becomes the acquiring processor if it ask for that when no acquiring processor exist, otherwise it has to wait for the acquiring processor to handle over the role to it. The acquiring processor will and will only assign one acquiring processor in the waiting list (if not empty) when it finishes its operation. - Acquiring device: the only device allowed to use the bus. Operations can be performed in either the BG or the task. When there's no acquiring device, only the ISR is allowed to be the acquiring processor and perform operations on the bus. When a device wants to perform operations, it either: 1. Acquire the bus, and operate in the task (e.g. polling transactions of SPI master, and SPI flash operations) 2. Request a BG operation. And the ISR will be enabled at proper time. For example if a task wants to send an interrupt transaction, it prepares the data in the task, call `spi_bus_lock_bg_request`, and handle sending in the ISR. 3. When a device has already acquired the bus, BG operations are also allowed. After the `spi_bus_lock_bg_request` is called, call `spi_bus_lock_wait_bg_done` before operations in task again to wait until BG operations are done. Any device may try to invoke the ISR (by `spi_bus_lock_bg_request`). The ISR will be invoked and become the acquiring processor immediately when the bus is not acquired by other processors. Any device may also try to acquire the bus (by `spi_bus_lock_acquire_start`). The device will become the acquiring processor immediately when the bus is not acquired and there is no request active. The acquiring processor must be aware of its acquiring role, and properly transfer the acquiring processor to other tasks or ISR when they have nothing else to do. Before picking a new acquiring processor, a new acquiring device must be picked first, if there are other devices, asking to be acquiring device. After that, the new acquiring processor is picked by the sequence below: 1. If there is an acquiring device: 1.1 The ISR, if acquiring device has active BG requests 1.2 The task of the device, if no active BG request for the device 2. The ISR, if there's no acquiring device, but any BG request is active 3. No one becomes the acquiring processor The API also helps on the arbitration of SPI cs lines. The bus is initialized with a cs_num argument. When attaching devices onto the bus with `spi_bus_lock_register_dev`, it will allocate devices with different device ID according to the flags given. If the ID is smaller than the cs_num given when bus is initialized, error will be returned. Usage: * Initialization: 1. Call `spi_bus_init_lock` to register a lock for a bus. 2. Call `spi_bus_lock_set_bg_control` to prepare BG enable/disable functions for the lock. 3. Call `spi_bus_lock_register_dev` for each devices that may make use of the bus, properly store the returned handle, representing those devices. * Acquiring: 1. Call `spi_bus_lock_acquire_start` when a device wants to use the bus 2. Call `spi_bus_lock_touch` to mark the bus as touched by this device. Also check if the bus has been touched by other devices. 3. (optional) Do something on the bus... 4. (optional) Call `spi_bus_lock_bg_request` to inform and invoke the BG. See ISR below about ISR operations. 5. (optional) If `spi_bus_lock_bg_request` is done, you have to call `spi_bus_lock_wait_bg_done` before touching the bus again, or do the following steps. 6. Call `spi_bus_lock_acquire_end` to release the bus to other devices. * ISR: 1. Call `spi_bus_lock_bg_entry` when entering the ISR, run or skip the closure for the previous operation according to the return value. 2. Call `spi_bus_lock_get_acquiring_dev` to get the acquiring device. If there is no acquiring device, call `spi_bus_lock_bg_check_dev_acq` to check and update a new acquiring device. 3. Call `spi_bus_lock_bg_check_dev_req` to check for request of the desired device. If the desired device is not requested, go to step 5. 4. Check, start operation for the desired device and go to step 6; otherwise if no operations can be performed, call `spi_bus_lock_bg_clear_req` to clear the request for this device. If `spi_bus_lock_bg_clear_req` is called and there is no BG requests active, goto step 6. 5. (optional) If the device is the acquiring device, go to step 6, otherwise find another desired device, and go back to step 3. 6. Call `spi_bus_lock_bg_exit` to try quitting the ISR. If failed, go back to step 2 to look for a new request again. Otherwise, quit the ISR. * Deinitialization (optional): 1. Call `spi_bus_lock_unregister_dev` for each device when they are no longer needed. 2. Call `spi_bus_deinit_lock` to release the resources occupied by the lock. Some technical details: The child-lock of each device will have its own Binary Semaphore, which allows the task serving this device (task A) being blocked when it fail to become the acquiring processor while it's calling `spi_bus_lock_acquire_start` or `spi_bus_lock_wait_bg_done`. If it is blocked, there must be an acquiring processor (either the ISR or another task (task B)), is doing transaction on the bus. After that, task A will get unblocked and become the acquiring processor when the ISR call `spi_bus_lock_bg_resume_acquired_dev`, or task B call `spi_bus_lock_acquire_end`. When the device wants to send ISR transaction, it should call `spi_bus_lock_bg_request` after the data is prepared. This function sets a request bit in the critical resource. The ISR will be invoked and become the new acquiring processor, when: 1. A task calls `spi_bus_lock_bg_request` while there is no acquiring processor; 2. A tasks calls `spi_bus_lock_bg_request` while the task is the acquiring processor. Then the acquiring processor is handled over to the ISR; 3. A tasks who is the acquiring processor release the bus by calling `spi_bus_lock_acquire_end`, and the ISR happens to be the next acquiring processor. The ISR will check (by `spi_bus_lock_bg_check_dev_req`) and clear a request bit (by `spi_bus_lock_bg_clear_req`) after it confirm that all the requests of the corresponding device are served. The request bit supports being written to recursively, which means, the task don't need to wait for `spi_bus_lock_bg_clear_req` before call another `spi_bus_lock_bg_request`. The API will handle the concurrency conflicts properly. The `spi_bus_lock_bg_exit` (together with `spi_bus_lock_bg_entry` called before)` is responsible to ensure ONE and ONLY ONE of the following will happen when the ISR try to give up its acquiring processor rule: 1. ISR quit, no any task unblocked while the interrupt disabled, and none of the BG bits is active. 2. ISR quit, there is an acquiring device, and the acquiring processor is passed to the task serving the acquiring device by unblocking the task. 3. The ISR failed to quit and have to try again.