docs/sched/sched: Add documentation for different sleep interfaces

[Lenoids]

Summary

As pull request #17200 & #17368 introduced support for scheduling sleep, a documentation is needed for different sleep interfaces. This patch adds the description for sleep interfaces currently provided in NuttX, including Scheduled sleep(nxsched_sleep()...), Signal-scheduled sleep(nxsig_sleep()...), and Busy sleep(up_udelay()).

Impact

Clarify and make developers easier to understand and choose proper sleep function in NuttX.

Testing

N/A. No impact over the codebase.

[Lenoids]

Hi, I saw build fail in xtensa-02), while the error log seems unrelated to this patch(looks like is No space left on device). Is there any way that I can manually retrigger the build process? @michallenc @xiaoxiang781216

fatal: write error: No space left on device
fatal: fetch-pack: invalid index-pack output
fatal: clone of 'https://github.com/espressif/esp32-wifi-lib.git' into submodule path '/github/workspace/sources/nuttx/arch/xtensa/src/esp32s2/esp-hal-3rdparty/components/esp_wifi/lib' failed
Failed to clone 'components/esp_wifi/lib'. Retry scheduled
fatal: write error: No space left on device
fatal: fetch-pack: invalid index-pack output
fatal: clone of 'https://github.com/espressif/esp32-wifi-lib.git' into submodule path '/github/workspace/sources/nuttx/arch/xtensa/src/esp32s2/esp-hal-3rdparty/components/esp_wifi/lib' failed
Failed to clone 'components/esp_wifi/lib' a second time, aborting
make[1]: *** [chip/Make.defs:196: context] Error 1
make: *** [tools/Unix.mk:458: arch/xtensa/src/.context] Error 2
make: Target 'all' not remade because of errors.

[simbit18]

Hi @lupyuen, could you please check what the storage space limit is on GitHub for NuttX? I do not have access to repository options.

[lupyuen]

@simbit18 NuttX Mirror Repo is failing with the same error: https://github.com/NuttX/nuttx/actions/runs/19887941188/job/56999535032#step:7:242

Maybe there's a problem with the ESP32 Repo? https://github.com/espressif/esp32-wifi-lib.git

[simbit18]

@lupyuen Now I will run a test on GitHub

[lupyuen]

@simbit18 Something odd about the build: It builds OK on my Home Build Farm (at a later timestamp). But fails at the NuttX Mirror Repo (at an earlier timestamp). Wonder why?

https://nuttx-dashboard.org/d/fe2bqg6uk7nr4a/build-logs-from-nuttx-build-farm?from=now-2d&to=now&timezone=browser&var-arch=$__all&var-subarch=$__all&var-board=esp32s2-saola-1&var-config=mcuboot_update_agent&var-group=$__all&var-Filters=

[lupyuen]

@simbit18 FYI the NuttX Mirror Repo has failed the build since this commit: b3caa67

https://nuttx-dashboard.org/d/fe2q876wubc3kc/nuttx-build-history?from=now-7d&to=now&timezone=browser&var-arch=$__all&var-subarch=$__all&var-board=esp32s2-saola-1&var-config=mcuboot_update_agent&var-group=$__all&var-Filters=user%7C%3D%7CNuttX

[simbit18]

@lupyuen This b3caa67 is my commit :)

[simbit18]

built with make on GitHub
./tools/configure.sh -l esp32s2-saola-1:mcuboot_update_agent
log

Register: wapi
make[3]: Leaving directory '/github/workspace/sources/apps/wireless/wapi'
make[2]: Leaving directory '/github/workspace/sources/apps'
make[2]: Entering directory '/github/workspace/sources/apps'
make[2]: Nothing to be done for 'context_wasm'.
make[2]: Leaving directory '/github/workspace/sources/apps'
make[1]: Leaving directory '/github/workspace/sources/apps'
make[1]: Entering directory '/github/workspace/sources/nuttx/arch/xtensa/src'
Cloning Espressif HAL for 3rd Party Platforms
Clone: chip/esp-hal-3rdparty 
if [ -z  ]; then git clone --quiet  https://github.com/espressif/esp-hal-3rdparty.git chip/esp-hal-3rdparty; else if [ ! -d  ]; then git clone --quiet  https://github.com/espressif/esp-hal-3rdparty.git ; fi; cp -fr  chip/esp-hal-3rdparty; fi
Espressif HAL for 3rd Party Platforms: 6b4f19b48c5ba0e847511b5b21584e797ec795dc
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
fatal: write error: No space left on device
fatal: fetch-pack: invalid index-pack output
fatal: clone of 'https://github.com/espressif/esp32-wifi-lib.git' into submodule path '/github/workspace/sources/nuttx/arch/xtensa/src/esp32s2/esp-hal-3rdparty/components/esp_wifi/lib' failed
Failed to clone 'components/esp_wifi/lib'. Retry scheduled
fatal: write error: No space left on device
fatal: fetch-pack: invalid index-pack output
fatal: clone of 'https://github.com/espressif/esp32-wifi-lib.git' into submodule path '/github/workspace/sources/nuttx/arch/xtensa/src/esp32s2/esp-hal-3rdparty/components/esp_wifi/lib' failed
Failed to clone 'components/esp_wifi/lib' a second time, aborting
make[1]: *** [chip/Make.defs:196: context] Error 1
make[1]: Leaving directory '/github/workspace/sources/nuttx/arch/xtensa/src'
make: *** [tools/Unix.mk:458: arch/xtensa/src/.context] Error 2

[lupyuen]

@simbit18 NuttX Mirror Repo builds OK now: https://github.com/NuttX/nuttx/actions/runs/19892799431

[simbit18]

@lupyuen Just for your information, this is the result of df -h on my repository with this configuration.
slowly rises like bread :)

Filesystem      Size  Used Avail Use% Mounted on
overlay          72G   72G  400M 100% /
tmpfs            64M     0   64M   0% /dev
shm              64M     0   64M   0% /dev/shm
/dev/root        72G   72G  400M 100% /github/runner_temp
tmpfs           3.2G  1.2M  3.2G   1% /run/docker.sock
tmpfs           7.9G     0  7.9G   0% /proc/acpi
tmpfs           7.9G     0  7.9G   0% /proc/scsi
tmpfs           7.9G     0  7.9G   0% /sys/firmware

[simbit18]

Hi @lupyuen , it's a space issue!
I ran some tests on GitHub.
Take a look here

https://github.com/simbit18/nuttx-testing-ci/actions/runs/19902259147/job/57049299454

• LinuxMake job without GitHub Action to free disk space
  The space available here is very limited, even without artifacts, etc.

.:Show disk usage:.
Filesystem      Size  Used Avail Use% Mounted on
overlay          72G   72G  236M 100% /
tmpfs            64M     0   64M   0% /dev
shm              64M     0   64M   0% /dev/shm
/dev/root        72G   72G  236M 100% /github/runner_temp
tmpfs           3.2G  1.2M  3.2G   1% /run/docker.sock
tmpfs           7.9G     0  7.9G   0% /proc/acpi
tmpfs           7.9G     0  7.9G   0% /proc/scsi
tmpfs           7.9G     0  7.9G   0% /sys/firmware

You can find a possible solution in the

• LinuxCleanup job with GitHub Action to free disk space

.:Show disk usage:.
Filesystem      Size  Used Avail Use% Mounted on
overlay          72G   60G   13G  84% /
tmpfs            64M     0   64M   0% /dev
shm              64M     0   64M   0% /dev/shm
/dev/root        72G   60G   13G  84% /github/home
tmpfs           3.2G  1.2M  3.2G   1% /run/docker.sock
tmpfs           7.9G     0  7.9G   0% /proc/acpi
tmpfs           7.9G     0  7.9G   0% /proc/scsi
tmpfs           7.9G     0  7.9G   0% /sys/firmware

Only Android runtime removed

      - name: Free Disk Space (Ubuntu)
        uses: ./.github/actions/free-disk-space
        with:
          # this might remove tools that are actually needed,
          # if set to "true" but frees about 6 GB
          tool-cache: false
          
          # all of these default to true, but feel free to set to
          # "false" if necessary for your workflow
          android: true
          dotnet: false
          haskell: false
          large-packages: false
          docker-images: false
          swap-storage: false 

Essentially, I reuse the action to free disk space on Ubuntu runner when when we create our NuttX Docker image.
(I have to go now, tomorrow I'll see what else can be done).

What do you think?

[lupyuen]

@simbit18 Yep let's try that thanks!

[simbit18]

NOTICE
I created this PR #17428 for fix

fatal: write error: No space left on device

after it has been merged, I will restart the entire workflow of this PR.

This PR is ok, I will use it as a verification test!

[simbit18]

@Lenoids, we need a rebase. Could you please do it?

[Lenoids]

@Lenoids, we need a rebase. Could you please do it?
@simbit18 Sure, let me try again.

This PR is ok, I will use it as a verification test!