In an OS that supports multiple tasks, modifying data in a memory area requires three steps: read data, modify data, and write data. However, data in a memory area may be simultaneously accessed by multiple tasks. If the data modification is interrupted by another task, the execution result of the operation is unpredictable.
In an OS that supports multiple tasks, modifying data in memory involves three steps: read data, modify data, and write data. However, the data may be simultaneously accessed by multiple tasks. If the data modification is interrupted by another task, an unexpected result will be caused.
Although you can enable or disable interrupts to ensure that the multi-task execution results meet expectations, the system performance is affected.
Although you can enable or disable interrupts to ensure expected results of multiple tasks, the system performance is affected.
The ARMv6 architecture has introduced the **LDREX** and **STREX** instructions to support more discreet non-blocking synchronization of the shared memory. The atomic operations implemented thereby can ensure that the "read-modify-write" operations on the same data will not be interrupted, that is, the operation atomicity is ensured.
The ARMv6 architecture has introduced the **LDREX** and **STREX** instructions to support more discreet non-blocking synchronization of the shared memory. The atomic operations implemented thereby can ensure that the "read-modify-write" operations on the same data will not be interrupted, that is, the operation atomicity is ensured.
## Working Principles
The OpenHarmony system has encapsulated the **LDREX** and **STREX** in the ARMv6 architecture to provide a set of atomic operation APIs.
- LDREX Rx, \[Ry\]
Reads the value in the memory and marks the exclusive access to the memory segment.
- Reads the 4-byte memory data pointed by the register **Ry** and saves the data to the **Rx** register.
- Adds an exclusive access flag to the memory area pointed by **Ry**.
- STREX Rf, Rx, \[Ry\]
Checks whether the memory has an exclusive access flag. If yes, the system updates the memory value and clears the flag. If no, the memory is not updated.
## Working Principles
- If there is an exclusive access flag, the system:
- Updates the **Rx** register value to the memory pointed to by the **Ry** register.
- Sets the **Rf** register to **0**.
OpenHarmony has encapsulated the **LDREX** and **STREX** in the ARMv6 architecture to provide a set of atomic operation APIs.
- If there is no exclusive access flag:
- The memory is not updated.
- The system sets the **Rf** register to **1**.
- LDREX Rx, [Ry]
Reads the value in the memory and marks the exclusive access to the memory segment.
- Reads the 4-byte memory data pointed by the register **Ry** and saves the data to the **Rx** register.
- Adds an exclusive access flag to the memory area pointed by **Ry**.
- STREX Rf, Rx, [Ry]
Checks whether the memory has an exclusive access flag. If yes, the system updates the memory value and clears the flag. If no, the memory is not updated.
- If there is an exclusive access flag, the system:
- Updates the **Rx** register value to the memory pointed to by the **Ry** register.
- Sets the **Rf** register to **0**.
- If there is no exclusive access flag:
- The memory is not updated.
- The system sets the **Rf** register to **1**.
-Flag register
- If the flag register is **0**, the system exits the loop and the atomic operation is complete.
- If the flag register is **1**, the system continues the loop and performs the atomic operation again.
- Flag register
- If the flag register is**0**, the system exits the loop and the atomic operation is complete.
- If the flag register is**1**, the system continues the loop and performs the atomic operation again.
## Development Guidelines
### Available APIs
The following table describes the APIs available for the OpenHarmony LiteOS-A kernel atomic operation module. For more details about the APIs, see the API reference.
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p59414511172"><aname="p59414511172"></a><aname="p59414511172"></a>Adds 1 to 32-bit atomic data and returns the data.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1194951111713"><aname="p1194951111713"></a><aname="p1194951111713"></a>Adds 1 to 64-bit atomic data and returns the data.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p198222414349"><aname="p198222414349"></a><aname="p198222414349"></a>Subtracts 1 from 32-bit atomic data and returns the result.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p198221841103419"><aname="p198221841103419"></a><aname="p198221841103419"></a>Subtracts 1 from 64-bit atomic data and returns the result.</p>
<trid="row149616511175"><tdclass="cellrowborder"rowspan="4"valign="top"width="21.21212121212121%"headers="mcps1.2.4.1.1 "><pid="p49615120172"><aname="p49615120172"></a><aname="p49615120172"></a>Compare and swap</p>
| Compare and swap| LOS_AtomicCmpXchgByte | Compares and swaps 8-bit memory data. |
| Compare and swap| LOS_AtomicCmpXchg16bits | Compares and swaps 16-bit memory data.|
| Compare and swap| LOS_AtomicCmpXchg32bits | Compares and swaps 32-bit memory data.|
| Compare and swap| LOS_AtomicCmpXchg64bits | Compares and swaps 64-bit memory data.|
### How to Develop
When multiple tasks perform addition, subtraction, and swap operations on the same memory data, use atomic operations to ensure predictability of results.
The software timer is a software-simulated timer based on system tick interrupts. When the preset tick counter value has elapsed, the user-defined callback will be invoked. The timing precision is related to the cycle of the system tick clock. Due to the limitation in hardware, the number of hardware timers cannot meet users' requirements. Therefore, the OpenHarmony LiteOS-A kernel provides the software timer function. The software timer allows more timing services to be created, increasing the number of timers.
The software timer is a software-simulated timer based on system tick interrupts. When the preset tick counter value has elapsed, the user-defined callback will be invoked. The timing precision is related to the cycle of the system tick clock.
Due to the limitation in hardware, the number of hardware timers cannot meet users' requirements. The OpenHarmony LiteOS-A kernel provides the software timer function.
The software timer allows more timing services to be created, increasing the number of timers.
The software timer supports the following functions:
- Disabling the software timer using a macro
- Creating a software timer
- Starting a software timer
- Stopping a software timer
- Deleting a software timer
- Obtaining the number of remaining ticks of a software timer
- Disabling the software timer using a macro
## Working Principles<a name="section31079397569"></a>
- Creating a software timer
The software timer is a system resource. When modules are initialized, a contiguous section of memory is allocated for software timers. The maximum number of timers supported by the system is configured by the **LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT** macro in **los\_config.h**. Software timers use a queue and a task resource of the system. The software timers are triggered based on the First In First Out \(FIFO\) rule. For the timers set at the same time, the timer with a shorter value is always closer to the queue head than the timer with a longer value, and is preferentially triggered. The software timer counts time in ticks. When a software timer is created and started, the OpenHarmony system determines the timer expiry time based on the current system time \(in ticks\) and the timing interval set by the user, and adds the timer control structure to the global timing list.
- Starting a software timer
- Stopping a software timer
- Deleting a software timer
- Obtaining the number of remaining ticks of a software timer
When a tick interrupt occurs, the tick interrupt handler scans the global timing list for expired timers. If such timers are found, the timers are recorded.
When the tick interrupt handling function is complete, the software timer task \(with the highest priority\) is woken up. In this task, the timeout callback function for the recorded timer is called.
## Working Principles
Timer States
The software timer is a system resource. When modules are initialized, a contiguous section of memory is allocated for software timers. The maximum number of timers supported by the system is configured by the **LOSCFG_BASE_CORE_SWTMR_LIMIT** macro in **los_config.h**.
- OS\_SWTMR\_STATUS\_UNUSED
Software timers use a queue and a task resource of the system. The software timers are triggered based on the First In First Out (FIFO) rule. For the timers set at the same time, the timer with a shorter value is always closer to the queue head than the timer with a longer value, and is preferentially triggered.
The timer is not in use. When the timer module is initialized, all timer resources in the system are set to this state.
The software timer counts time in ticks. When a software timer is created and started, the OpenHarmony system determines the timer expiry time based on the current system time (in ticks) and the timing interval set by the user, and adds the timer control structure to the global timing list.
- OS\_SWTMR\_STATUS\_CREATED
When a tick interrupt occurs, the tick interrupt handler scans the global timing list for expired timers. If such timers are found, the timers are recorded.
When the tick interrupt handler is complete, the software timer task (with the highest priority) will be woken up. In this task, the timeout callback for the recorded timer is called.
The timer is created but not started or the timer is stopped. When **LOS\_SwtmrCreate** is called for a timer that is not in use or **LOS\_SwtmrStop** is called for a newly started timer, the timer changes to this state.
A software timer can be in any of the following states:
- OS\_SWTMR\_STATUS\_TICKING
- OS_SWTMR_STATUS_UNUSED
The timer is not in use. When the timer module is initialized, all timer resources in the system are set to this state.
- OS_SWTMR_STATUS_CREATED
The timer is running \(counting\). When **LOS\_SwtmrStart** is called for a newly created timer, the timer enters this state.
The timer is created but not started or the timer is stopped. When **LOS_SwtmrCreate** is called for a timer that is not in use or **LOS_SwtmrStop** is called for a newly started timer, the timer changes to this state.
- OS_SWTMR_STATUS_TICKING
Timer Modes
The timer is running (counting). When **LOS_SwtmrStart** is called for a newly created timer, the timer enters this state.
The OpenHarmony provides three types of software timers:
OpenHarmony provides three types of software timers:
- One-shot timer: Once started, the timer is automatically deleted after triggering only one timer event.
- Periodic timer: This type of timer periodically triggers timer events until it is manually stopped.
- One-shot timer deleted by calling an API
## Development Guidelines<a name="section18576131520577"></a>
### Available APIs<a name="section3138019145719"></a>
The following table describes APIs available for the OpenHarmony LiteOS-A software timer module. For more details about the APIs, see the API reference.
<tbody><trid="row1470413222429"><tdclass="cellrowborder"rowspan="2"valign="top"width="20.6020602060206%"headers="mcps1.2.4.1.1 "><pid="p8284115918428"><aname="p8284115918428"></a><aname="p8284115918428"></a>Creating or deleting timers</p>
<tdclass="cellrowborder"valign="top"width="49.85498549854985%"headers="mcps1.2.4.1.3 "><pid="p170422234213"><aname="p170422234213"></a><aname="p170422234213"></a>Creates a software timer.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p870442211421"><aname="p870442211421"></a><aname="p870442211421"></a>Deletes a software timer.</p>
</td>
</tr>
<trid="row57041422184215"><tdclass="cellrowborder"rowspan="2"valign="top"width="20.6020602060206%"headers="mcps1.2.4.1.1 "><pid="p1476172124318"><aname="p1476172124318"></a><aname="p1476172124318"></a>Starting or stopping timers</p>
<tdclass="cellrowborder"valign="top"width="49.85498549854985%"headers="mcps1.2.4.1.3 "><pid="p1570412229421"><aname="p1570412229421"></a><aname="p1570412229421"></a>Starts a software timer.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p17705122211426"><aname="p17705122211426"></a><aname="p17705122211426"></a>Stops a software timer.</p>
</td>
</tr>
<trid="row12705222154214"><tdclass="cellrowborder"valign="top"width="20.6020602060206%"headers="mcps1.2.4.1.1 "><pid="p0705622134214"><aname="p0705622134214"></a><aname="p0705622134214"></a>Obtaining remaining ticks of a software timer</p>
<tdclass="cellrowborder"valign="top"width="49.85498549854985%"headers="mcps1.2.4.1.3 "><pid="p3705122264210"><aname="p3705122264210"></a><aname="p3705122264210"></a>Obtains the number of remaining ticks of a software timer.</p>
</td>
</tr>
</tbody>
</table>
### How to Develop<a name="section1344817403575"></a>
## Development Guidelines
### Available APIs
The following table describes the APIs of the software timer module of the OpenHarmony LiteOS-A kernel.
>- Avoid too many operations in the callback function of the software timer. Do not use APIs or perform operations that may cause task suspension or blocking.
>- The software timers use a queue and a task resource of the system. The priority of the software timer tasks is set to **0** and cannot be changed.
>- The number of software timer resources that can be configured in the system is the total number of software timer resources available to the entire system, not the number of software timer resources available to users. For example, if the system software timer occupies one more resource, the number of software timer resources available to users decreases by one.
>- If a one-shot software timer is created, the system automatically deletes the timer and reclaims resources after the timer times out and the callback function is executed.
>- For a one-shot software timer that will not be automatically deleted after expiration, you need to call **LOS\_SwtmrDelete** to delete it and reclaim the timer resource to prevent resource leakage.
6. Call **LOS_SwtmrDelete** to delete the software timer.
### Development Example<a name="section114416313585"></a>
> **NOTE**<br>
>
> - Avoid too many operations in the callback of the software timer. Do not use APIs or perform operations that may cause task suspension or blocking.
>
> - The software timers use a queue and a task resource of the system. The priority of the software timer tasks is set to **0** and cannot be changed.
>
> - The number of software timer resources that can be configured in the system is the total number of software timer resources available to the entire system, not the number of software timer resources available to users. For example, if the system software timer occupies one more resource, the number of software timer resources available to users decreases by one.
>
> - If a one-shot software timer is created, the system automatically deletes the timer and reclaims resources after the timer times out and the callback is invoked.
>
> - For a one-shot software timer that will not be automatically deleted after expiration, you need to call **LOS_SwtmrDelete** to delete it and reclaim the timer resource to prevent resource leakage.
Prerequisites:
- In **los\_config.h**, **LOSCFG\_BASE\_CORE\_SWTMR** is enabled.
- The maximum number of software timers supported by the system \(**LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT**\) is configured.
- The maximum length of the software timer queue \(**OS\_SWTMR\_HANDLE\_QUEUE\_SIZE**\) is configured.
### Development Example
**Prerequisites**
- In **los_config.h**, **LOSCFG_BASE_CORE_SWTMR** is enabled.
- The maximum number of software timers supported by the system (**LOSCFG_BASE_CORE_SWTMR_LIMIT**) is configured.
- The maximum length of the software timer queue (**OS_SWTMR_HANDLE_QUEUE_SIZE**) is configured.
**Sample Code**
...
...
@@ -164,14 +150,14 @@ void Timer_example(void)
UINT16 id2; // timer id
UINT32 uwTick;
/* Create a one-shot software timer, with the number of ticks set to 1000. When the number of ticks reaches 1000, callback function 1 is executed. */
/* Create a one-shot software timer, with the number of ticks set to 1000. Callback 1 will be invoked when the number of ticks reaches 1000. */
Time management provides all time-related services for applications based on the system clock. The system clock is generated by the interrupts triggered by the output pulse of a timer or counter. The system clock is generally defined as an integer or a long integer. The period of an output pulse is a "clock tick". The system clock is also called time scale or tick. The duration of a tick can be configured statically. People use second or millisecond as the time unit, while the operating system uses tick. When operations such as suspending a task or delaying a task are performed, the time management module converts time between ticks and seconds or milliseconds.
Time management is performed based on the system clock. It provides time-related services for applications. The system clock is generated by the interrupts triggered by the output pulse of a timer or counter. The system clock is generally defined as an integer or a long integer. The period of an output pulse is a "clock tick".
The system clock is also called time scale or tick. The duration of a tick can be configured statically. People use second or millisecond as the time unit, while the operating system uses tick. When operations such as suspending a task or delaying a task are performed, the time management module converts time between ticks and seconds or milliseconds.
The mapping between ticks and seconds can be configured.
-**Cycle**
- Cycle
Cycle is the minimum time unit in the system. The cycle duration is determined by the system clock frequency, that is, the number of cycles per second.
- Tick
Cycle is the minimum time unit in the system. The cycle duration is determined by the system clock frequency, that is, the number of cycles per second.
Tick is the basic time unit of the operating system and is determined by the number of ticks per second configured by the user.
The OpenHarmony time management module provides time conversion, statistics, and delay functions.
-**Tick**
Tick is the basic time unit of the operating system and is determined by the number of ticks per second configured by the user.
## Development Guidelines
Before you start, learn about the system time and the APIs for time management.
The OpenHarmony time management module provides time conversion, statistics, and delay functions to meet users' time requirements.
## Development Guidelines
### Available APIs
The time management module provides APIs to implement conversion between the system running time, ticks, and seconds/milliseconds.
The following table describes APIs for OpenHarmony LiteOS-A time management. For more details about the APIs, see the API reference.
<tdclass="cellrowborder"valign="top"width="33.33333333333333%"headers="mcps1.2.4.1.3 "><pid="p8504121996"><aname="p8504121996"></a><aname="p8504121996"></a>Converts milliseconds into ticks.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p161632181721"><aname="p161632181721"></a><aname="p161632181721"></a>Converts ticks into milliseconds.</p>
<tdclass="cellrowborder"valign="top"width="33.33333333333333%"headers="mcps1.2.4.1.3 "><pid="p615864811116"><aname="p615864811116"></a><aname="p615864811116"></a>Obtains the current number of ticks.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p151631718124"><aname="p151631718124"></a><aname="p151631718124"></a>Obtains the number of cycles per tick.</p>
</td>
</tr>
</tbody>
</table>
### How to Develop
1. Call APIs to convert time.
2. Call APIs to perform time statistics.
1. Call APIs to convert time.
2. Call APIs to perform time statistics.
> **NOTE**
>
> - The system tick count can be obtained only after the system clock is enabled.
>
> - The time management module depends on **OS_SYS_CLOCK** and **LOSCFG_BASE_CORE_TICK_PER_SECOND** in **los_config.h**.
>
> - The number of system ticks is not counted when the interrupt feature is disabled. Therefore, the number of ticks cannot be used as the accurate time.
>- The system tick count can be obtained only after the system clock is enabled.
>- The time management module depends on **OS\_SYS\_CLOCK** and **LOSCFG\_BASE\_CORE\_TICK\_PER\_SECOND** in **los\_config.h**.
>- The number of system ticks is not counted when the interrupt feature is disabled. Therefore, the number of ticks cannot be used as the accurate time.
### Development Example
**Prerequisites**<br>
**Prerequisites**
The following parameters are configured:
-**LOSCFG\_BASE\_CORE\_TICK\_PER\_SECOND**: number of ticks per second in the system. The value range is (0, 1000].
-**OS\_SYS\_CLOCK**: system clock, in Hz.
-**LOSCFG_BASE_CORE_TICK_PER_SECOND**: number of ticks/second. The value range is (0, 1000).
@@ -9,29 +9,25 @@ A mutex has three attributes: protocol attribute, priority upper limit attribute
- LOS_MUX_PRIO_NONE
Do not inherit or protect the priority of the task requesting the mutex.
Do not inherit or protect the priority of the task requesting the mutex.
- LOS_MUX_PRIO_INHERIT
Inherits the priority of the task that requests the mutex. This is the default protocol attribute. When the mutex protocol attribute is set to this value: If a task with a higher priority is blocked because the mutex is already held by a task, the priority of the task holding the mutex will be backed up to the priority bitmap of the task control block, and then set to be the same as that of the task of a higher priority. When the task holding the mutex releases the mutex, its task priority is restored to its original value.
Inherits the priority of the task that requests the mutex. This is the default protocol attribute. When the mutex protocol attribute is set to this value: If a task with a higher priority is blocked because the mutex is already held by a task, the priority of the task holding the mutex will be backed up to the priority bitmap of the task control block, and then set to be the same as that of the task of a higher priority. When the task holding the mutex releases the mutex, its task priority is restored to its original value.
- LOS_MUX_PRIO_PROTECT
Protects the priority of the task that requests the mutex. When the mutex protocol attribute is set to this value: If the priority of the task that requests the mutex is lower than the upper limit of the mutex priority, the task priority will be backed up to the priority bitmap of the task control block, and then set to the upper limit value of the mutex priority. When the mutex is released, the task priority is restored to its original value.
The type attribute of a mutex specifies whether to check for deadlocks and whether to support recursive holding of the mutex. The type attribute can be any of the following:
The type attribute of a mutex specifies whether to check for deadlocks and whether to support recursive holding of the mutex. The type attribute can be any of the following:
- LOS_MUX_NORMAL
Common mutex, which does not check for deadlocks. If a task repeatedly attempts to hold a mutex, the thread will be deadlocked. If the mutex type attribute is set to this value, a task cannot release a mutex held by another task or repeatedly release a mutex. Otherwise, unexpected results will be caused.
Common mutex, which does not check for deadlocks. If a task repeatedly attempts to hold a mutex, the thread will be deadlocked. If the mutex type attribute is set to this value, a task cannot release a mutex held by another task or repeatedly release a mutex. Otherwise, unexpected results will be caused.
- LOS_MUX_RECURSIVE
Recursive mutex, which is the default attribute. If the type attribute of a mutex is set to this value, a task can hold the mutex for multiple times. Another task can hold this mutex only when the number of lock holding times is the same as the number of lock release times. However, any attempt to hold a mutex held by another task or attempt to release a mutex that has been released will return an error code.
Recursive mutex, which is the default attribute. If the type attribute of a mutex is set to this value, a task can hold the mutex for multiple times. Another task can hold this mutex only when the number of lock holding times is the same as the number of lock release times. However, any attempt to hold a mutex held by another task or attempt to release a mutex that has been released will return an error code.
- LOS_MUX_ERRORCHECK
...
...
@@ -44,7 +40,7 @@ In a multi-task environment, multiple tasks may access the same shared resources
When non-shared resources are accessed by a task, the mutex is locked. Other tasks will be blocked until the mutex is released by the task. The mutex allows only one task to access the shared resources at a time, ensuring integrity of operations on the shared resources.
**Figure 1** Mutex working mechanism for the small system
**Figure 1** Mutex working mechanism for the small system
Fast userspace mutex \(futex\) is a system call capability provided by the kernel. It is a basic component that combines with user-mode lock logic to form a user-mode lock. It is a lock working in both user mode and kernel mode, for example, userspace mutex, barrier and cond synchronization lock, and RW lock. The user-mode part implements lock logic, and the kernel-mode part schedules locks.
Fast userspace mutex (futex) is a system call capability provided by the kernel. It is a basic component that combines with user-mode lock logic to form a user-mode lock. It is a lock working in both user mode and kernel mode, for example, userspace mutex, barrier and cond synchronization lock, and RW lock. The user-mode part implements lock logic, and the kernel-mode part schedules locks.
When a user-mode thread requests a lock, the lock status is first checked in user space. If no lock contention occurs, the user-mode thread acquires the lock directly. If lock contention occurs, the futex system call is invoked to request the kernel to suspend the thread and maintain the blocking queue.
When a user-mode thread releases a lock, the lock status is first checked in user space. If no other thread is blocked by the lock, the lock is directly released in user space. If there are threads blocked by the lock, the futex system call is invoked to request the kernel to wake up the threads in the blocking queue.
## Working Principles<a name="section16834132502910"></a>
## Working Principles
When thread scheduling is required to resolve lock contention or lock release in user space, the futex system call is invoked to pass the user-mode lock address to the kernel. The user-mode locks are distinguished by lock address in the futex of the kernel. The available virtual address space in user space is 1 GiB. To facilitate search and management of lock addresses, the kernel futex uses hash buckets to store the user-mode locks.
There are 80 hash buckets. Buckets 0 to 63 are used to store private locks \(hashed based on virtual addresses\), and buckets 64 to 79 are used to store shared locks \(hashed based on physical addresses\). The private/shared attributes are determined by initialization of user-mode locks and the input parameters in the futex system call.
There are 80 hash buckets used to store shared locks (hashed based on physical addresses). The private/shared attributes are determined by initialization of user-mode locks and the input parameters in the futex system call.
As shown in the above figure, each futex hash bucket stores the futex nodes with the same hash value linked in a futex\_list. Each futex node corresponds to a suspended task. The key value of a node uniquely identifies a user-mode lock. The nodes with the same key value added to a queue\_list indicate a queue of tasks blocked by the same lock.
The following table describes the APIs available for the futex module.
<tbody><trid="row04981218910"><tdclass="cellrowborder"valign="top"width="27.09270927092709%"headers="mcps1.2.4.1.1 "><pid="p6462616696"><aname="p6462616696"></a><aname="p6462616696"></a>Putting a thread to wait</p>
<tdclass="cellrowborder"valign="top"width="46.384638463846386%"headers="mcps1.2.4.1.3 "><pid="p8504121996"><aname="p8504121996"></a><aname="p8504121996"></a>Inserts a node representing a blocked thread into the futex list.</p>
</td>
</tr>
<trid="row7162101814216"><tdclass="cellrowborder"valign="top"width="27.09270927092709%"headers="mcps1.2.4.1.1 "><pid="p37331032985"><aname="p37331032985"></a><aname="p37331032985"></a>Waking up a thread</p>
<tdclass="cellrowborder"valign="top"width="46.384638463846386%"headers="mcps1.2.4.1.3 "><pid="p161632181721"><aname="p161632181721"></a><aname="p161632181721"></a>Wakes up a thread that is blocked by a specified lock.</p>
</td>
</tr>
<trid="row101631818620"><tdclass="cellrowborder"valign="top"width="27.09270927092709%"headers="mcps1.2.4.1.1 "><pid="p146111936887"><aname="p146111936887"></a><aname="p146111936887"></a>Modifying the lock address</p>
<tdclass="cellrowborder"valign="top"width="46.384638463846386%"headers="mcps1.2.4.1.3 "><pid="p151631718124"><aname="p151631718124"></a><aname="p151631718124"></a>Adjusts the position of a specified lock in the futex list.</p>
>The futex system call and user-mode logic form a user-mode lock. Therefore, you are advised to use the locks via the user-mode POSIX APIs.
As shown in the above figure, each futex hash bucket stores the futex nodes with the same hash value linked in a futex_list. Each futex node corresponds to a suspended task. The key value of a node uniquely identifies a user-mode lock. The nodes with the same key value added to a queue_list indicate a queue of tasks blocked by the same lock.
Signal is a common inter-process asynchronous communication mechanism. It uses software-simulated interrupt signals. When a process needs to communicate with another process, it sends a signal to the kernel. The kernel then transfers the signal to the destination process. The destination process does not need to wait for the signal.
Signal is a common asynchronous communication mechanism between processes. It uses software-simulated interrupt signals. When a process needs to communicate with another process, it sends a signal to the kernel. The kernel transfers the signal to the target process. The target process does not need to wait for the signal.
## Working Principles<a name="section1249693812301"></a>
The following table describes the APIs available for signal operations.
## Working Principles
**Table 1** Signal operation process and APIs \(user-mode APIs\)
The following table describes the APIs for signal operations.
<tbody><trid="row04981218910"><tdclass="cellrowborder"rowspan="2"valign="top"width="27.09270927092709%"headers="mcps1.2.4.1.1 "><pid="p6462616696"><aname="p6462616696"></a><aname="p6462616696"></a>Registering the signal callback</p>
<tdclass="cellrowborder"valign="top"width="46.41464146414641%"headers="mcps1.2.4.1.3 "><pid="p8504121996"><aname="p8504121996"></a><aname="p8504121996"></a>Registers the main signal entry, and registers and unregisters the callback function of a signal.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1945083962113"><aname="p1945083962113"></a><aname="p1945083962113"></a>Same as <strongid="b1076755712371"><aname="b1076755712371"></a><aname="b1076755712371"></a>signal</strong>. This API is added with configuration options related to signal transmission. Currently, only some parameters in the <strongid="b18458105019218"><aname="b18458105019218"></a><aname="b18458105019218"></a>SIGINFO</strong> structure are supported.</p>
<tdclass="cellrowborder"rowspan="5"align="left"valign="top"width="46.41464146414641%"headers="mcps1.2.4.1.3 "><pid="p161632181721"><aname="p161632181721"></a><aname="p161632181721"></a>Sends a signal to a process or sends messages to a thread in a process, and sets signal flags for threads in a process.</p>
<trid="row101631818620"><tdclass="cellrowborder"valign="top"width="27.09270927092709%"headers="mcps1.2.4.1.1 "><pid="p146111936887"><aname="p146111936887"></a><aname="p146111936887"></a>Triggering a callback</p>
<tdclass="cellrowborder"valign="top"width="46.41464146414641%"headers="mcps1.2.4.1.3 "><pid="p1126941694213"><aname="p1126941694213"></a><aname="p1126941694213"></a>Triggered by a system call or an interrupt. Before the switching between the kernel mode and user mode, the specified function in user mode is entered, and the corresponding callbacks are processed. After that, the original user-mode program continues to run.</p>
>You can obtain and modify the configuration of signal registration. Currently, only the **SIGINFO** options are supported. For details, see the description of the **sigtimedwait** API.
>Transmit a signal.
>a. Among the default signal-receiving behaviors, the process does not support **STOP**, **CONTINUE**, and **COREDUMP** defined in the POSIX standard.
>b. The **SIGSTOP**, **SIGKILL**, and **SIGCONT** signals cannot be shielded.
>c. If a process killed is not reclaimed by its parent process, the process becomes a zombie process.
>d. A process will not call back the signal received until the process is scheduled.
>e. When a process is killed, **SIGCHLD** is sent to its parent process. The signal sending action cannot be canceled.
>f. A process in the DELAY state cannot be woken up by a signal.
| Registering/Unregistering a signal callback| signal | Registers the main signal entry, and registers or unregisters a callback for a signal. |
| Registering a signal callback| sigaction | Same as **signal**. This API is added with configuration options related to signal transmission. Currently, only some parameters in the **SIGINFO** structure are supported.|
| Sending a signal | kill<br>pthread_kill<br>raise<br>alarm<br>abort | Sends a signal to a process or sends a message to a thread in a process, and sets the signal flag for a thread in a process. |
| Invoking a callback | NA | Called by a system call or an interrupt. Before the switching between the kernel mode and user mode, the callback in the specified function in user mode is processed. After that, the original user-mode program continues to run.|
> **NOTE**<br>
> The signal mechanism enables communication between user-mode programs. The user-mode POSIX APIs listed in the above table are recommended.
>
> **Registering a Callback**
>
>
> ```
> void *signal(int sig, void (*func)(int))(int);
> ```
>
> - Signal 31 is used to register the handling entry of the process callback. Repeated registration is not allowed.
>
>
> - Signals 0 to 30 are used to register and unregister callbacks.
>
>
> **Registering a Callback**
>
>
> ```
> int sigaction(int, const struct sigaction ***restrict, struct sigaction ***restrict);
> ```
>
> You can obtain and modify the configuration of signal registration. Currently, only the **SIGINFO** options are supported. For details, see the description of the **sigtimedwait** API.
>
> **Sending a Signal**
>
> - Among the default signal-receiving behaviors, the process does not support **STOP**, **COTINUE**, and **COREDUMP** defined in POSIX.
>
>
> - The **SIGSTOP**, **SIGKILL**, and **SIGCONT** signals cannot be shielded.
>
>
> - If a process killed is not reclaimed by its parent process, the process becomes a zombie process.
>
>
> - A process will not call back the signal received until the process is scheduled.
>
>
> - When a process is killed, **SIGCHLD** is sent to its parent process. The signal sending action cannot be canceled.
>
>
> - A process in the DELAY state cannot be woken up by a signal.
LiteIPC is a new inter-process communication \(IPC\) mechanism provided by the OpenHarmony LiteOS-A kernel. Different from the traditional System V IPC, LiteIPC is designed for Remote Procedure Call \(RPC\). In addition, it provides APIs for the upper layer through device files, not through traditional API functions.
LiteIPC has two important concepts: ServiceManager and Service. The entire system can have one ServiceManager and multiple Services. ServiceManager is responsible for registering and unregistering Services, and managing Service access permission \(only authorized tasks can send IPC messages to corresponding Services\).
## Working Principles<a name="section849811592918"></a>
ServiceManager registers the task that needs to receive IPC messages as a Service, and sets the access permission for the Service task \(specifies the tasks that can send IPC messages to the Service\). LiteIPC maintains an IPC message queue for each Service task in kernel mode. The message queue provides the upper-layer user-mode programs with the read operation \(receiving IPC messages\) and the write operations \(sending IPC messages\) through LiteIPC device files.
## Development Guidelines<a name="section17571315171017"></a>
### Available APIs<a name="section725022011103"></a>
**Table 1** LiteIPC module APIs \(for LiteOS-A internal use only\)
<tdclass="cellrowborder"valign="top"width="57.34573457345735%"headers="mcps1.2.4.1.3 "><pid="p48623102592"><aname="p48623102592"></a><aname="p48623102592"></a>Initializes the LiteIPC module.</p>
<tdclass="cellrowborder"valign="top"width="57.34573457345735%"headers="mcps1.2.4.1.3 "><pid="p1886211011599"><aname="p1886211011599"></a><aname="p1886211011599"></a>Initializes the IPC message memory pool of processes.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p586261085913"><aname="p586261085913"></a><aname="p586261085913"></a>Re-initializes the IPC message memory pool of processes.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p555221518598"><aname="p555221518598"></a><aname="p555221518598"></a>Releases the IPC message memory pool of processes.</p>
<tdclass="cellrowborder"valign="top"width="57.34573457345735%"headers="mcps1.2.4.1.3 "><pid="p1555261595915"><aname="p1555261595915"></a><aname="p1555261595915"></a>Deletes the specified Service.</p>
>LiteIPC module APIs are used for LiteOS-A internal use only.
## Basic Concepts
LiteIPC is a new inter-process communication (IPC) mechanism provided by the OpenHarmony LiteOS-A kernel. Different from the traditional System V IPC, LiteIPC is designed for Remote Procedure Call (RPC). In addition, it provides APIs for the upper layer through device files, not through traditional API functions.
LiteIPC has two important concepts: ServiceManager and Service. The entire system can have one ServiceManager and multiple Services.
ServiceManager provides the following functions:
- Registers and deregisters services.
- Manages the access permission of services. Only authorized tasks can send IPC messages to the service.
## Working Principles
ServiceManager registers the task that needs to receive IPC messages as a Service, and sets the access permission for the Service task (specifies the tasks that can send IPC messages to the Service).
LiteIPC maintains an IPC message queue for each Service task in kernel mode. The message queue provides the upper-layer user-mode programs with the read operation (receiving IPC messages) and the write operations (sending IPC messages) through LiteIPC device files.
## Development Guidelines
### Available APIs
**Table 1** APIs of the LiteIPC module (applicable to LiteOS-A only)
| Module initialization | **OsLiteIpcInit**: initializes the LiteIPC module. |
| IPC message memory pool| - **LiteIpcPoolInit**: initializes the IPC message memory pool of a process.<br>- **LiteIpcPoolReInit**: reinitializes the IPC message memory pool of a process.<br>- **LiteIpcPoolDelete**: releases the IPC message memory pool of a process. |
| Service management | **LiteIpcRemoveServiceHandle**: deletes a service. |
> **NOTE**<br>
> The APIs of the LiteIPC module are dedicated for LiteOS-A internal use only.
The OpenHarmony dynamic loading and linking mechanism includes a kernel loader and a dynamic linker. The kernel loader loads application programs and the dynamic linker. The dynamic linker loads the shared library on which the application programs depend, and performs symbol relocation for the application programs and shared libraries. Compared with static linking, dynamic linking is a mechanism for delaying the linking of applications and dynamic libraries to run time.
**Advantages of Dynamic Linking**
1. Dynamic linking allows multiple applications to share code. The minimum loading unit is page. Dynamic linking saves disk and memory space than static linking.
2. When a shared library is upgraded, the new shared library overwrites the earlier version \(the APIs of the shared library are downward compatible\). You do not need to re-link the shared library.
3. The loading address can be randomized to prevent attacks and ensure security.
- Dynamic linking allows multiple applications to share code. The minimum loading unit is page. Dynamic linking saves disk and memory space than static linking.
- When a shared library is upgraded, the new shared library overwrites the earlier version (the APIs of the shared library are downward compatible). You do not need to re-link the shared library.
- The loading address can be randomized to prevent attacks and ensure security.
## Working Principles
## Working Principles<a name="section14140155320511"></a>
1. The kernel maps the **PT\_LOAD** section in the ELF file of the application to the process space. For files of the ET\_EXEC type, fixed address mapping is performed based on **p\_vaddr** in the **PT\_LOAD** section. For files of the ET\_DYN type \(position-independent executable programs, obtained through the compile option **-fPIE**\), the kernel selects the **base** address via **mmap** for mapping \(load\_addr = base + p\_vaddr\).
2. If the application is statically linked \(static linking does not support the compile option **-fPIE**\), after the stack information is set, the system redirects to the address specified by **e\_entry** in the ELF file of the application and runs the application. If the program is dynamically linked, the application ELF file contains the **PT\_INTERP** section, which stores the dynamic linker path information \(ET\_DYN type\). The dynamic linker of musl is a part of the **libc-musl.so**. The entry of **libc-musl.so** is the entry of the dynamic linker. The kernel selects the **base** address for mapping via the **mmap** API, sets the stack information, redirects to the **base + e\_entry**\(entry of the dynamic linker\) address, and runs the dynamic linker.
3. The dynamic linker bootstraps and searches for all shared libraries on which the application depends, relocates the imported symbols, and finally redirects to the **e\_entry**\(or **base + e\_entry**\) of the application to run the application.
1. The kernel maps the **PT_LOAD** section in the ELF file of the application to the process space. For files of the ET_EXEC type, fixed address mapping is performed based on **p_vaddr** in the **PT_LOAD** section. For files of the ET_DYN type (position-independent executable programs, obtained through **-fPIE**), the kernel selects the **base** address via **mmap** for mapping (load_addr = base + p_vaddr).
2. If the application is statically linked (static linking does not support **-fPIE**), after the stack information is set, the system redirects to the address specified by **e_entry** in the ELF file of the application and runs the application. If the program is dynamically linked, the application ELF file contains the **PT_INTERP** section, which stores the dynamic linker path information (ET_DYN type). The dynamic linker of musl is a part of the **libc-musl.so**. The entry of **libc-musl.so** is the entry of the dynamic linker. The kernel selects the **base** address for mapping via the **mmap** API, sets the stack information, redirects to the **base + e_entry** (entry of the dynamic linker) address, and runs the dynamic linker.
3. The dynamic linker bootstraps and searches for all shared libraries on which the application depends, relocates the imported symbols, and finally redirects to the **e_entry** (or **base + e_entry**) of the application to run the application.
**Figure 2** Program execution process
**Figure 2** Program execution process<aname="fig17879151310447"></a>
1. The loader and linker call **mmap** to map the **PT\_LOAD** section.
2. The kernel calls **map\_pages** to search for and map the existing PageCache.
3. If there is no physical memory for mapping in the virtual memory region during program execution, the system triggers a page missing interrupt, which allows the ELF file to be read into the physical memory and adds the memory block to the pagecache.
4. Map the physical memory blocks of the file read to the virtual address region.
5. The program continues to run.
## Development Guidelines<a name="section133501496612"></a>
### Available APIs<a name="section874113201669"></a>
<tdclass="cellrowborder"valign="top"width="57.34573457345735%"headers="mcps1.2.4.1.3 "><pid="p48623102592"><aname="p48623102592"></a><aname="p48623102592"></a>Executes the specified user program based on the input parameters.</p>
</td>
</tr>
</tbody>
</table>
### How to Develop<a name="section196712561563"></a>
The kernel cannot directly call the **LOS\_DoExecveFile** API to start a new process. This API is generally called through the **exec\(\)** API to create a new process using the system call mechanism.
1. The loader and linker call **mmap** to map the **PT_LOAD** section.
2. The kernel calls **map_pages** to search for and map the existing PageCache.
3. If there is no physical memory for mapping in the virtual memory region during program execution, the system triggers a page missing interrupt, which allows the ELF file to be read into the physical memory and adds the memory block to the pagecache.
4. Map the physical memory blocks of the file read to the virtual address region.
| Starting initialization| LOS_DoExecveFile | Executes the specified user program based on the input parameters.|
### How to Develop
The kernel cannot directly call the **LOS_DoExecveFile** API to start a new process. This API is generally called through the **exec()** API to create a new process using the system call mechanism.
Different from a common dynamic shared library, which stores its .so files in the file system, the virtual dynamic shared object \(VDSO\) has its .so files stored in the system image. The kernel determines the .so files needed and provides them to the application program. That is why the VDSO is called a virtual dynamic shared library.
## Basic Concepts
The VDSO mechanism allows OpenHarmony user-mode programs to quickly obtain kernel-related data. It can accelerate certain system calls and implement quick read of non-sensitive data \(hardware and software configuration\).
Different from a common dynamic shared library, which stores its .so files in the file system, the virtual dynamic shared object (VDSO) has its .so files stored in the system image. The kernel determines the .so files needed and provides them to the application program. That is why the VDSO is called a virtual dynamic shared library.
## Working Principles<a name="section546363114810"></a>
The VDSO mechanism allows OpenHarmony user-mode programs to quickly obtain kernel-related data. It can accelerate certain system calls and implement quick read of non-sensitive data (hardware and software configuration).
The VDSO can be regarded as a section of memory \(read-only\) maintained by the kernel and mapped to the address space of the user-mode applications. By linking **vdso.so**, the applications can directly access this mapped memory instead of invoking system calls, accelerating application execution.
## Working Principles
The VDSO can be regarded as a section of memory (read-only) maintained by the kernel and mapped to the address space of the user-mode applications. By linking **vdso.so**, the applications can directly access this mapped memory instead of invoking system calls, accelerating application execution.
VDSO can be divided into:
- Data page: provides the kernel-time data mapped to the user process.
- Code page: provides the logic for shielding system calls.
- Data page: provides the kernel-time data mapped to the user process.
- Code page: provides the logic for shielding system calls.
**Figure 1** VDSO system design
**Figure 1** VDSO system design<aname="fig1986131094711"></a>
>- The VDSO mechanism supports the **CLOCK\_REALTIME\_COARSE** and **CLOCK\_MONOTONIC\_COARSE** functions of the **clock\_gettime** API in the LibC library. For details about how to use the **clock\_gettime** API, see the POSIX standard. You can call **clock\_gettime\(CLOCK\_REALTIME\_COARSE, &ts\)** or **clock\_gettime\(CLOCK\_MONOTONIC\_COARSE, &ts\)** of the LibC library to use the VDSO.
>- When VDSO is used, the time precision is the same as that of the tick interrupt of the system. The VDSO mechanism is applicable to the scenario where there is no demand for high time precision and **clock\_gettime** or **gettimeofday** is frequently triggered in a short period of time. The VDSO mechanism is not recommended for the system demanding high time precision.
> **NOTE**<br>
>
> - The VDSO mechanism supports the **CLOCK_REALTIME_COARSE** and **CLOCK_MONOTONIC_COARSE** functions of the **clock_gettime** API in the LibC library. For details about how to use the **clock_gettime** API, see the POSIX standard.
>
> - You can call **clock_gettime(CLOCK_REALTIME_COARSE, &ts)** or **clock_gettime(CLOCK_MONOTONIC_COARSE, &ts)** of the Libc library to use the VDSO.
>
> - When VDSO is used, the time precision is the same as that of the tick interrupt of the system. The VDSO mechanism is applicable to the scenario where there is no demand for high time precision and **clock_gettime** or **gettimeofday** is frequently triggered in a short period of time. The VDSO mechanism is not recommended for the system demanding high time precision.
<tdclass="cellrowborder"valign="top"width="56.99999999999999%"headers="mcps1.2.4.1.2 "><aname="ul1530071303413"></a><aname="ul1530071303413"></a><ulid="ul1530071303413"><li>Displays the CPU usage of the system within the last 10 seconds by default.</li><li><strongid="b13709113084810"><aname="b13709113084810"></a><aname="b13709113084810"></a>0</strong>: displays the CPU usage within the last 10 seconds.</li><li><strongid="b10788133319480"><aname="b10788133319480"></a><aname="b10788133319480"></a>1</strong>: displays the CPU usage within the last 1 second.</li><li>Other value: displays the total CPU usage since the system is started.</li></ul>
<tdclass="cellrowborder"valign="top"width="56.99999999999999%"headers="mcps1.2.4.1.2 "><pid="p3799mcpsimp"><aname="p3799mcpsimp"></a><aname="p3799mcpsimp"></a>Specifies the task ID.</p>
- If no parameter is specified, the CPU usage of the system within the last 10 seconds is displayed.
- If only **mode** is specified, the CPU usage within the specified period is displayed.
- If both **mode** and **taskID** are specified, the CPU usage of the specified task within the given period is displayed.
| Parameter| Description| Value Range|
| -------- | -------- | -------- |
| mode | Displays the CPUP of the system within the last 10 seconds by default.<br>- **0**: displays the CPUP within the last 10 seconds.<br>- **1**: displays the CPUP within the last 1 second.<br>- Other numbers: display the total CPUP since the system starts.| [0, 0xFFFFFFFF] |
| taskID | Specifies the task ID.| [0, 0xFFFFFFFF] |
## Example<a name="section68501605319"></a>
Run **cpup 1 5**.
## Usage Guidelines
## Output<a name="section19871522144219"></a>
- If no parameter is specified, the CPU usage of the system within the last 10 seconds is displayed.
- If only **mode** is specified, the CPU usage within the specified period is displayed.
- If both **mode** and **taskID** are specified, the CPU usage of the specified task within the given period is displayed.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.4.1.2 "><pid="p1162201234017"><aname="p1162201234017"></a><aname="p1162201234017"></a>Displays help information.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.4.1.2 "><pid="p26216124407"><aname="p26216124407"></a><aname="p26216124407"></a>Prints the date and time in the specified <strongid="b115041849185916"><aname="b115041849185916"></a><aname="b115041849185916"></a>Format</strong>.</p>
</td>
<tdclass="cellrowborder"valign="top"width="28.999999999999996%"headers="mcps1.2.4.1.3 "><pid="p46251220409"><aname="p46251220409"></a><aname="p46251220409"></a>Placeholders listed in <strongid="b36588246116"><aname="b36588246116"></a><aname="b36588246116"></a>--help</strong></p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.4.1.2 "><pid="p136291219403"><aname="p136291219403"></a><aname="p136291219403"></a>Displays UTC instead of the current time zone.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3917mcpsimp"><aname="p3917mcpsimp"></a><aname="p3917mcpsimp"></a>Prints content in the buffer and clears the buffer.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3924mcpsimp"><aname="p3924mcpsimp"></a><aname="p3924mcpsimp"></a>Clears the buffer.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3931mcpsimp"><aname="p3931mcpsimp"></a><aname="p3931mcpsimp"></a>Disables or enables printing to the console.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3938mcpsimp"><aname="p3938mcpsimp"></a><aname="p3938mcpsimp"></a>Disables or enables printing via the serial port.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3945mcpsimp"><aname="p3945mcpsimp"></a><aname="p3945mcpsimp"></a>Sets the size of the buffer.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3952mcpsimp"><aname="p3952mcpsimp"></a><aname="p3952mcpsimp"></a>Sets the buffering level.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p717417317512"><aname="p717417317512"></a><aname="p717417317512"></a>Writes the content in the buffer to the specified file.</p>
- This command depends on **LOSCFG\_SHELL\_DMESG**. Before using this command, select **Enable Shell dmesg** on **menuconfig**.
Debug ---\> Enable a Debug Version ---\> Enable Shell ---\> Enable Shell dmesg
- If no parameter is specified, all content in the buffer is printed.
- The parameters followed by hyphens \(-\) are mutually exclusive.
1. Before writing content to a file, ensure that the file system has been mounted.
2. Disabling the serial port printing will adversely affect shell. You are advised to set up a connection using Telnet before disabling the serial port.
## Example<a name="section13736564418"></a>
Run **dmesg\> dmesg.log**.
## Output<a name="section194005101413"></a>
Writing the content in the buffer to the **dmesg.log** file:
| > fileA | Writes the content in the buffer to a file. | N/A |
## Usage Guidelines
- This command can be used only after **LOSCFG_SHELL_DMESG** is enabled. To enable **LOSCFG_SHELL_DMESG**, run the **make menuconfig** command in **kernel/liteos_a**. In the displayed dialog box, locate the **Debug** option and set **Enable Shell dmesg** to **Yes**.
Debug ---> Enable a Debug Version ---> Enable Shell ---> Enable Shell dmesg
- If no parameter is specified, all content in the buffer is printed.
- The parameters followed by hyphens (-) are mutually exclusive.
1. Before writing content to a file, ensure that the file system has been mounted.
2. Disabling the serial port printing will adversely affect shell. You are advised to set up a connection using Telnet before disabling the serial port.
## Example
Run **dmesg> dmesg.log**.
## Output
Write the content in the buffer to the **dmesg.log** file.
| executable-file | Specifies a valid executable file.|
## Usage Guidelines
Currently, this command supports only valid binary programs. The programs are successfully executed and then run in the background by default. However, the programs share the same device with the shell. As a result, the output of the programs and the shell may be interlaced.
>After the executable file is executed, the prompt **OHOS \#** is printed first. The shell **exec** command is executed in the background, causing the prompt to be printed in advance.
> **NOTE**<br>
> After the executable file is executed, the prompt **OHOS #** is printed first. The shell **exec** command is executed in the background, causing the prompt to be printed in advance.
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p64861302212"><aname="p64861302212"></a><aname="p64861302212"></a>Displays the memory usage in bytes.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1648617012214"><aname="p1648617012214"></a><aname="p1648617012214"></a>Displays the parameters supported by the <strongid="b1247315411335"><aname="b1247315411335"></a><aname="b1247315411335"></a>free</strong> command.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p54864013214"><aname="p54864013214"></a><aname="p54864013214"></a>Displays the memory usage in bytes.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1648670192120"><aname="p1648670192120"></a><aname="p1648670192120"></a>Displays the memory usage in KiB.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p134869022114"><aname="p134869022114"></a><aname="p134869022114"></a>Displays the memory usage in MiB.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p348680122118"><aname="p348680122118"></a><aname="p348680122118"></a>Displays the memory usage in GiB.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p18486140132118"><aname="p18486140132118"></a><aname="p18486140132118"></a>Displays the memory usage in TiB.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1737315202218"><aname="p1737315202218"></a><aname="p1737315202218"></a>Total size of the dynamic memory pool</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p197376156222"><aname="p197376156222"></a><aname="p197376156222"></a>Size of the used memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p97371915142218"><aname="p97371915142218"></a><aname="p97371915142218"></a>Size of the unallocated memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1773801514223"><aname="p1773801514223"></a><aname="p1773801514223"></a>Size of the shared memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p157381015192216"><aname="p157381015192216"></a><aname="p157381015192216"></a>Size of the buffer</p>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p1323011409405"><a name="p1323011409405"></a><a name="p1323011409405"></a>CPU usage within the last 10 seconds</p>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p76814443417"><a name="p76814443417"></a><a name="p76814443417"></a>CPU usage within the last 1 second</p>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.2.3.1.2 "><p id="p268134415419"><a name="p268134415419"></a><a name="p268134415419"></a>Interrupt type, which can be any of the following:</p>
<tdclass="cellrowborder"valign="top"width="51.92%"headers="mcps1.2.4.1.2 "><pid="p3402191493310"><aname="p3402191493310"></a><aname="p3402191493310"></a>Displays the parameters supported by the <strongid="b277973411569"><aname="b277973411569"></a><aname="b277973411569"></a>kill</strong> command.</p>
<tdclass="cellrowborder"valign="top"width="51.92%"headers="mcps1.2.4.1.2 "><pid="p640281413313"><aname="p640281413313"></a><aname="p640281413313"></a>Lists the names and numbers of signals.</p>
<tdclass="cellrowborder"valign="top"width="51.92%"headers="mcps1.2.4.1.2 "><pid="p114023144336"><aname="p114023144336"></a><aname="p114023144336"></a>Specifies the signal number.</p>
<tdclass="cellrowborder"valign="top"width="51.92%"headers="mcps1.2.4.1.2 "><pid="p7402014113310"><aname="p7402014113310"></a><aname="p7402014113310"></a>Specifies the process ID.</p>
>The value range of **signo** is \[0, 64\]. The recommended value range is \[1, 30\], and other values in the value range are reserved.
## Usage<a name="section15935131220717"></a>
- The **signo** and **pid** parameters are mandatory.
- The **pid** value range varies depending on the system configuration. For example, if the maximum **pid** value supported by the system is **256**, this value range is \[1-256\].
## Example<a name="section79281818476"></a>
- Query the process list before killing process 42.
```
OHOS:/$ ps
allCpu(%): 4.67 sys, 195.33 idle
PID PPID PGID UID Status VirtualMem ShareMem PhysicalMem CPUUSE10s PName
- Send signal 9 \(the default action of **SIGKILL** is to immediately terminate the process\) to process 42 test\_demo \(a user-mode process\). Then, check the current process list. The commands **kill -s 9 42** and **kill -9 42** have the same effect.
```
OHOS:/$ kill -s 9 42
OHOS:/$
[1] + Killed ./nfs/test_demo
OHOS:/$ ps
allCpu(%): 4.73 sys, 195.27 idle
PID PPID PGID UID Status VirtualMem ShareMem PhysicalMem CPUUSE10s PName
| --help | Displays the parameters supported by the **kill** command.| N/A |
| -l | Lists the names and numbers of signals. | N/A |
| -s | Sends a signal. | N/A |
| signo | Specifies the signal number. | [1, 30] |
| pid | Specifies the process ID. | [1, MAX_INT] |
> **NOTICE**<br>
> The value range of **signo** is [0, 64]. The recommended value range is [1, 30], and other values in the value range are reserved.
## Usage Guidelines
- The **signo** and **pid** parameters are mandatory.
- The **pid** value range varies depending on the system configuration. For example, if the maximum **pid** value supported by the system is **256**, this value range is [1, 256].
## Note
The **kill** command is not supported by the shell. mksh supports it. To switch to mksh, run **cd bin;** and **./mksh**.
## Example
- Query the process list before killing process 42.
```
OHOS:/$ ps
allCpu(%): 4.67 sys, 195.33 idle
PID PPID PGID UID Status VirtualMem ShareMem PhysicalMem CPUUSE10s PName
- Send signal 9 (the default action of **SIGKILL** is to immediately terminate the process) to process 42 test_demo (a user-mode process). Then, check the current process list. The commands **kill -s 9 42** and **kill -9 42** have the same effect.
```
OHOS:/$ kill -s 9 42
OHOS:/$
[1] + Killed ./nfs/test_demo
OHOS:/$ ps
allCpu(%): 4.73 sys, 195.27 idle
PID PPID PGID UID Status VirtualMem ShareMem PhysicalMem CPUUSE10s PName
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p254mcpsimp"><aname="p254mcpsimp"></a><aname="p254mcpsimp"></a>Specifies the level of logs to print.</p>
This command is used to check whether the dynamically allocated memory block is complete and whether nodes in the memory pool are damaged due to out-of-bounds memory access.
## Syntax<a name="section428816435510"></a>
## Syntax
memcheck
## Parameters<a name="section1939943304411"></a>
None
## Parameters
None.
## Usage Guidelines
## Usage<a name="section228914491951"></a>
- If all nodes in the memory pool are complete, "system memcheck over, all passed!" is displayed.
- If all nodes in the memory pool are complete, "system memcheck over, all passed!" is displayed.
- If a node in the memory pool is incomplete, information about the memory block of the corrupted node is displayed.
- If a node in the memory pool is incomplete, information about the memory block of the corrupted node is displayed.
## Example<a name="section17373205314515"></a>
Run **memcheck**.
## Example
## Output<a name="section13406205385413"></a>
Run **memcheck**.
Example 1: All nodes in the memory pool are complete.
Run **memcheck**, and memory overwriting occurs.
## Output
Example 1: No error is detected.
```
OHOS # memcheck
system memcheck over, all passed!
```
Example 2: Out-of-bounds memory access is detected.
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1149945111817"><aname="p1149945111817"></a><aname="p1149945111817"></a>Sets the interval (in ms) for checking the Out Of Memory (OOM) thread task.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p749810571812"><aname="p749810571812"></a><aname="p749810571812"></a>100 to 10000</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p2058485315912"><aname="p2058485315912"></a><aname="p2058485315912"></a>Sets the low memory threshold (in MB).</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p1584105318917"><aname="p1584105318917"></a><aname="p1584105318917"></a>0 (disables the low memory check) to 1</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p159263241121"><aname="p159263241121"></a><aname="p159263241121"></a>Sets the PageCache reclaim threshold.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p692642412121"><aname="p692642412121"></a><aname="p692642412121"></a>Ranging from the low memory threshold to the maximum available system memory</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p9762113775517"><aname="p9762113775517"></a><aname="p9762113775517"></a>Displays help information.</p>
| -i [interval] | Sets the interval (in ms) for checking the Out Of Memory (OOM) thread task.| [100, 10000] |
| -m [mem byte] | Sets the low memory threshold (in MB). | 0 to 1<br>The value **0** means not to perform the low memory threshold check. |
| -r [mem byte] | Sets the PageCache reclaim threshold. | Low memory threshold to the maximum available memory of the system<br>Generally, the size of a PageCache is 4 KB. Sometimes, it is 16 KB to 64 KB. |
<tbody><trid="row502mcpsimp"><tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.1 "><pid="p583513382179"><aname="p583513382179"></a><aname="p583513382179"></a>[oom] OS is in low memory state</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p19833143819174"><aname="p19833143819174"></a><aname="p19833143819174"></a>The operating system has low memory.</p>
<pid="p83883291587"><aname="p83883291587"></a><aname="p83883291587"></a>The available physical memory in the operating system is <strongid="b15343050123397"><aname="b15343050123397"></a><aname="b15343050123397"></a>0x1bcf000</strong> bytes, <strongid="b18697901323397"><aname="b18697901323397"></a><aname="b18697901323397"></a>0x1b50000</strong> bytes have been used, and <strongid="b3252944373397"><aname="b3252944373397"></a><aname="b3252944373397"></a>0x7f000</strong> bytes are available. The current low memory threshold is <strongid="b13811086363397"><aname="b13811086363397"></a><aname="b13811086363397"></a>0x80000</strong> bytes.</p>
</td>
</tr>
<trid="row1990234224612"><tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.1 "><pid="p3902144294612"><aname="p3902144294612"></a><aname="p3902144294612"></a>[oom] candidate victim process init pid: 1, actual phy mem byte: 82602</p>
</td>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p13903144284610"><aname="p13903144284610"></a><aname="p13903144284610"></a>Memory usage of each process. The physical memory occupied by the <strongid="b143686319910"><aname="b143686319910"></a><aname="b143686319910"></a>init</strong> process is 82602 bytes.</p>
</td>
</tr>
<trid="row520212272335"><tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.1 "><pid="p172038278339"><aname="p172038278339"></a><aname="p172038278339"></a>[oom] candidate victim process UserProcess12 pid: 12, actual phy mem byte: 25951558</p>
</td>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p112034276331"><aname="p112034276331"></a><aname="p112034276331"></a>The actual memory used by the <strongid="b16405477923397"><aname="b16405477923397"></a><aname="b16405477923397"></a>UserProcess12</strong> process is <strongid="b10952024983397"><aname="b10952024983397"></a><aname="b10952024983397"></a>25951558</strong> bytes.</p>
</td>
</tr>
<trid="row3273195033416"><tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.1 "><pid="p184989213512"><aname="p184989213512"></a><aname="p184989213512"></a>[oom] max phy mem used process UserProcess12 pid: 12, actual phy mem: 25951558</p>
</td>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p112741750143417"><aname="p112741750143417"></a><aname="p112741750143417"></a>The process that uses the most memory currently is <strongid="b17770979863397"><aname="b17770979863397"></a><aname="b17770979863397"></a>UserProcess12</strong>.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p6452818367"><aname="p6452818367"></a><aname="p6452818367"></a>The system memory is low, and the <strongid="b4088490143397"><aname="b4088490143397"></a><aname="b4088490143397"></a>UserProcess12</strong> process fails to apply for memory and exits.</p>
| [oom] OS is in low memory state<br>total physical memory: 0x1bcf000(byte), used: 0x1b50000(byte), free: 0x7f000(byte), low memory threshold: 0x80000(byte) | The OS has low memory.<br>The total physical memory is **0x1bcf000** bytes, **0x1b50000** bytes are used, and **0x7f000** bytes are left.<br/>The current lower memory threshold is **0x80000** bytes. |
| [oom] candidate victim process init pid: 1, actual phy mem byte: 82602 | The memory occupied by the **init** process is 82602 bytes. |
| [oom] candidate victim process UserProcess12 pid: 12, actual phy mem byte: 25951558 | The memory used by the **UserProcess12** process is **25951558** bytes. |
| [oom] max phy mem used process UserProcess12 pid: 12, actual phy mem: 25951558 | The process that uses the most memory currently is **UserProcess12**. |
| excFrom: User! | The system memory is low, and the **UserProcess12** process fails to apply for memory and exits. |
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1058062614579"><aname="p1058062614579"></a><aname="p1058062614579"></a>Address of the physical page control block</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1858082617577"><aname="p1858082617577"></a><aname="p1858082617577"></a>First physical page address, that is, start address of the physical page memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p85808262572"><aname="p85808262572"></a><aname="p85808262572"></a>Size of the physical page memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1139715117599"><aname="p1139715117599"></a><aname="p1139715117599"></a>Number of active anonymous pages in the page cache</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1341012355019"><aname="p1341012355019"></a><aname="p1341012355019"></a>Number of inactive anonymous pages in the page cache</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1267012382019"><aname="p1267012382019"></a><aname="p1267012382019"></a>Number of active file pages in the page cache</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p17966174115018"><aname="p17966174115018"></a><aname="p17966174115018"></a>Number of inactive file pages in the page cache</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1616375952018"><aname="p1616375952018"></a><aname="p1616375952018"></a><strongid="b161631659162014"><aname="b161631659162014"></a><aname="b161631659162014"></a>total</strong>: total number of physical pages.</p>
<pid="p2029802122113"><aname="p2029802122113"></a><aname="p2029802122113"></a><strongid="b429822122113"><aname="b429822122113"></a><aname="b429822122113"></a>used</strong>: number of used physical pages.</p>
<pid="p1218312452014"><aname="p1218312452014"></a><aname="p1218312452014"></a><strongid="b132798755433826"><aname="b132798755433826"></a><aname="b132798755433826"></a>free</strong>: number of free physical pages.</p>
</td>
</tr>
</tbody>
</table>
**Table 1** Output description
| Parameter| Description|
| -------- | -------- |
| phys_seg | Address of the physical page control block.|
| base | First physical page address, that is, start address of the physical page memory.|
| size | Size of the physical page memory.|
| free_pages | Number of free physical pages.|
| active anon | Number of active anonymous pages in the page cache.|
| inactive anon | Number of inactive anonymous pages in the page cache.|
| active file | Number of active file pages in the page cache.|
| inactive file | Number of inactive file pages in the page cache.|
| pmm pages | **total** indicates the total number of physical pages. <br/>**used** indicates the number of used physical pages. <br/>**free** indicates the number of idle physical pages. |
This command is used to query information about kernel semaphores.
## Syntax<a name="section8833164614615"></a>
sem \[_ID__ / fulldata_\]
## Syntax
sem [_ID__ / fulldata_]
## Parameters
**Table 1** Parameter description
## Parameters<a name="section12809111019453"></a>
| Parameter| Description| Value Range|
| -------- | -------- | -------- |
| ID | Specifies the semaphore ID.| [0, 1023] or [0x0, 0x3FF]|
| fulldata | Displays information about all semaphores in use. <br/>The displayed information includes **SemID**, **Count**, **Original Count**, **Creator TaskEntry**, and **Last Access Time**. | N/A |
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p455mcpsimp"><aname="p455mcpsimp"></a><aname="p455mcpsimp"></a>Specifies the semaphore ID.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p14422125918562"><aname="p14422125918562"></a><aname="p14422125918562"></a>[0, 1023] or [0x0, 0x3FF]</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p462mcpsimp"><aname="p462mcpsimp"></a><aname="p462mcpsimp"></a>Queries information about all the semaphores in use. The information includes <strongid="b189454249533849"><aname="b189454249533849"></a><aname="b189454249533849"></a>SemID</strong>, <strongid="b162724654333849"><aname="b162724654333849"></a><aname="b162724654333849"></a>Count</strong>, <strongid="b111325307233849"><aname="b111325307233849"></a><aname="b111325307233849"></a>OriginalCount</strong>, <strongid="b182850346833849"><aname="b182850346833849"></a><aname="b182850346833849"></a>Creator(TaskEntry)</strong>, and <strongid="b213750533633849"><aname="b213750533633849"></a><aname="b213750533633849"></a>LastAccessTime</strong>.</p>
- If no parameter is specified, this command displays the semaphore IDs and the number of times that each semaphore is used.
- If no parameter is specified, this command displays the semaphore IDs and the number of times that each semaphore is used.
- If **ID** is specified, the use of the specified semaphore is displayed.
- The **fulldata** parameter depends on **LOSCFG\_DEBUG\_SEMAPHORE**. Before using this parameter, select **Enable Semaphore Debugging** on **menuconfig**.
- If **ID** is specified, the use of the specified semaphore is displayed.
Debug ---\> Enable a Debug Version ---\> Enable Debug LiteOS Kernel Resource ---\> Enable Semaphore Debugging
- The **fulldata** parameter depends on **LOSCFG_DEBUG_SEMAPHORE**. Before using this parameter, set **Enable Semaphore Debugging** to **Yes** on **menuconfig**.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p506mcpsimp"><aname="p506mcpsimp"></a><aname="p506mcpsimp"></a>Number of times that the semaphore is used</p>
>The **ID** value can be in decimal or hexadecimal format.
>When **ID** is a value within \[0, 1023\], semaphore information of the specified ID is displayed. If the specified semaphore is not used, a message is displayed to inform you of this case. For other values, a message is displayed indicating that the parameter is incorrect.
**Table 2** Output description
| Parameter| Description|
| -------- | -------- |
| SemID | Semaphore ID.|
| Count | Number of times that the semaphore is used.|
> **NOTE**<br>
> The **ID** value can be in decimal or hexadecimal format.
>
> When **ID** is a value within [0, 1023], semaphore information of the specified ID is displayed. If the specified semaphore is not used, a message is displayed to inform you of this case. For other values, a message is displayed indicating that the parameter is incorrect.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1829104012416"><aname="p1829104012416"></a><aname="p1829104012416"></a>Number of times that the semaphore is used</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p282916401148"><aname="p282916401148"></a><aname="p282916401148"></a>Original count of the semaphore</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p168298407419"><aname="p168298407419"></a><aname="p168298407419"></a>Address of the entry function of the thread used to create the semaphore</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p198292406412"><aname="p198292406412"></a><aname="p198292406412"></a>Last time when the semaphore was accessed</p>
</td>
</tr>
</tbody>
</table>
**Table 3** Output description
| Parameter| Description|
| -------- | -------- |
| SemID | Semaphore ID.|
| Count | Number of times that the semaphore is used.|
| OriginalCount | Original count of the semaphore.|
| Creator | Address of the entry function of the thread used to create the semaphore.|
| LastAccessTime | Last time when the semaphore was accessed.|
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p647mcpsimp"><aname="p647mcpsimp"></a><aname="p647mcpsimp"></a>Name of the stack</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1510024539"><aname="p1510024539"></a><aname="p1510024539"></a>Size of the stack used</p>
<tdclass="cellrowborder"valign="top"width="51.93%"headers="mcps1.2.4.1.2 "><pid="p14138191243"><aname="p14138191243"></a><aname="p14138191243"></a>Specifies the ID of the target user.</p>
<tdclass="cellrowborder"valign="top"width="51.93%"headers="mcps1.2.4.1.2 "><pid="p48748461789"><aname="p48748461789"></a><aname="p48748461789"></a>Specifies the ID of the target user group.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p534mcpsimp"><aname="p534mcpsimp"></a><aname="p534mcpsimp"></a>Specifies the ID of a software timer.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p565mcpsimp"><aname="p565mcpsimp"></a><aname="p565mcpsimp"></a>ID of the software timer</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p570mcpsimp"><aname="p570mcpsimp"></a><aname="p570mcpsimp"></a>Status of the software timer</p>
<pid="p88402543474"><aname="p88402543474"></a><aname="p88402543474"></a>The value can be <strongid="b164905263633836"><aname="b164905263633836"></a><aname="b164905263633836"></a>UnUsed</strong>, <strongid="b138979237833836"><aname="b138979237833836"></a><aname="b138979237833836"></a>Created</strong>, or <strongid="b3849463233836"><aname="b3849463233836"></a><aname="b3849463233836"></a>Ticking</strong>.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p575mcpsimp"><aname="p575mcpsimp"></a><aname="p575mcpsimp"></a>Mode of the software timer</p>
<pid="p657320204499"><aname="p657320204499"></a><aname="p657320204499"></a>The value can be <strongid="b201632419733836"><aname="b201632419733836"></a><aname="b201632419733836"></a>Once</strong>, <strongid="b45281151733836"><aname="b45281151733836"></a><aname="b45281151733836"></a>Period</strong>, or <strongid="b73443815433836"><aname="b73443815433836"></a><aname="b73443815433836"></a>NSD</strong> (one-shot timer that will not be automatically deleted after the timer has expired).</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p580mcpsimp"><aname="p580mcpsimp"></a><aname="p580mcpsimp"></a>Number of ticks for the software timer</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p585mcpsimp"><aname="p585mcpsimp"></a><aname="p585mcpsimp"></a>Number of times that the software timer has been used</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p595mcpsimp"><aname="p595mcpsimp"></a><aname="p595mcpsimp"></a>Address of the callback</p>
>- The **ID** value can be in decimal or hexadecimal format.
>- If the **ID** value is within the range of \[0, _Number of current software timers - 1_\], the status of the specified software timer is returned. For other values, an error message is displayed.
**Table 2** Output description
| Parameter| Description|
| -------- | -------- |
| SwTmrID | ID of the software timer.|
| State | Status of the software timer.<br>The status may be **UnUsed**, **Created**, or **Ticking**.|
| Mode | Mode of the software timer.<br>The value can be **Once**, **Period**, or **NSD** (one-shot timer that will not be automatically deleted after the timer has expired).|
| Interval | Number of ticks for the software timer.|
| Count | Number of times that the software timer has been used.|
| Arg | Input parameter.|
| handlerAddr | Address of the callback.|
> **NOTE**<br>
> - The **ID** value can be in decimal or hexadecimal format.
>
> - If the **ID** value is within the range of [0, *Number of current software timers - 1*], the status of the specified software timer is returned. Otherwise, an error code is returned.
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p662mcpsimp"><aname="p662mcpsimp"></a><aname="p662mcpsimp"></a>Whether the module is enabled</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p689mcpsimp"><aname="p689mcpsimp"></a><aname="p689mcpsimp"></a>Displays all information.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1062611511398"><aname="p1062611511398"></a><aname="p1062611511398"></a>Parent process ID</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p2068355383916"><aname="p2068355383916"></a><aname="p2068355383916"></a>Process group ID</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p2011611331604"><aname="p2011611331604"></a><aname="p2011611331604"></a>CPU usage within last 10 seconds</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p843mcpsimp"><aname="p843mcpsimp"></a><aname="p843mcpsimp"></a>Size of the task stack</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p848mcpsimp"><aname="p848mcpsimp"></a><aname="p848mcpsimp"></a>Peak value of the stack used</p>
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p942673885313"><aname="p942673885313"></a><aname="p942673885313"></a>Displays the parameters supported by the <strongid="b2435956125215"><aname="b2435956125215"></a><aname="b2435956125215"></a>top</strong> command.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p19723153055519"><aname="p19723153055519"></a><aname="p19723153055519"></a>Parent process ID</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p117231630165519"><aname="p117231630165519"></a><aname="p117231630165519"></a>Process group ID</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1172323019556"><aname="p1172323019556"></a><aname="p1172323019556"></a>CPU usage within last 10 seconds</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p8724930135519"><aname="p8724930135519"></a><aname="p8724930135519"></a>Size of the task stack</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p10724103013559"><aname="p10724103013559"></a><aname="p10724103013559"></a>Peak value of the stack used</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p1664862551411"><aname="p1664862551411"></a><aname="p1664862551411"></a>Displays help information.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p186484252141"><aname="p186484252141"></a><aname="p186484252141"></a>Displays the operating system name by default.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p864872512145"><aname="p864872512145"></a><aname="p864872512145"></a>Displays all information.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p1064852514149"><aname="p1064852514149"></a><aname="p1064852514149"></a>Displays the operating system name.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p136489251143"><aname="p136489251143"></a><aname="p136489251143"></a>Displays the operating system architecture name.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p6648132512141"><aname="p6648132512141"></a><aname="p6648132512141"></a>Displays the network domain name of the host.</p>
<tdclass="cellrowborder"valign="top"width="66.01%"headers="mcps1.2.3.1.2 "><pid="p46489250149"><aname="p46489250149"></a><aname="p46489250149"></a>Displays version information.</p>
</td>
</tr>
</tbody>
</table>
## Usage<a name="section2652124861114"></a>
- The **uname** command displays the name of the current operating system by default.
- Except **--help** and **-a**, other parameters can be used together. **uname -a** is equivalent to **uname -srmnv**.
## Example<a name="section0107995132"></a>
## Syntax
uname [_-a | -s | -r | -m | -n | -v | --help_]
**Table 1** Parameter description
| Parameter | Description |
| ------ | ----------------------- |
| --help | Displays help information.|
| No parameter| Displays the operating system name by default. |
| -a | Displays all data. |
| -s | Displays the operating system name. |
| -r | Displays the kernel release version. |
| -m | Displays the operating system architecture name. |
| -n | Displays the network domain name of the host. |
| -v | Displays version information. |
## Usage Guidelines
- The **uname** command displays the name of the current operating system by default.
- Except **--help** and **-a**, other parameters can be used together. **uname -a** is equivalent to **uname -srmnv**.
## Note
The **-r**, **-m**, and **-n** parameters are not supported currently. mksh supports these parameters. To switch to mksh, run **cd bin** and **./mksh**.
## Example
Run the following commands:
- uname -a
- uname -ms
- uname -a
- uname -ms
## Output<a name="section1215113245511"></a>
## Output
Example 1: all information of the operating system
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p209441344121716"><aname="p209441344121716"></a><aname="p209441344121716"></a>Displays the virtual memory usage of all processes.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1494494441713"><aname="p1494494441713"></a><aname="p1494494441713"></a>Displays help information.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1594515442177"><aname="p1594515442177"></a><aname="p1594515442177"></a>Specifies the ID of the process to query.</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p9137130122311"><aname="p9137130122311"></a><aname="p9137130122311"></a>Address of the virtual memory control block</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1613783082319"><aname="p1613783082319"></a><aname="p1613783082319"></a>Start address of the virtual memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p18137143092313"><aname="p18137143092313"></a><aname="p18137143092313"></a>Size of virtual memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p5137130142314"><aname="p5137130142314"></a><aname="p5137130142314"></a>Number of used physical pages</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p1795344642412"><aname="p1795344642412"></a><aname="p1795344642412"></a>Address of the control block in the virtual memory region</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p19539466245"><aname="p19539466245"></a><aname="p19539466245"></a>Name of the virtual memory region</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p139536468242"><aname="p139536468242"></a><aname="p139536468242"></a>Start address of the virtual memory region</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p89531246142419"><aname="p89531246142419"></a><aname="p89531246142419"></a>Size of the virtual memory region</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p395464620242"><aname="p395464620242"></a><aname="p395464620242"></a>MMU mapping attribute of the virtual memory region</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p29541546112416"><aname="p29541546112416"></a><aname="p29541546112416"></a>Number of used physical pages, including that of the shared memory</p>
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.2.3.1.2 "><pid="p10954164642419"><aname="p10954164642419"></a><aname="p10954164642419"></a>Number of used physical pages</p>
</td>
</tr>
</tbody>
</table>
**Table 2** Basic process information
| Parameter| Description|
| -------- | -------- |
| PID | Process ID.|
| aspace | Address of the virtual memory control block.|
| name | Process name.|
| base | Start address of the virtual memory.|
| size | Total Virtual Memory.|
| pages | Number of used physical pages.|
**Table 3** Virtual memory interval information
| Parameter| Description|
| -------- | -------- |
| region | Address of the control block in the virtual memory region.|
| name | Name of the virtual memory region.|
| base | Start address of the virtual memory region.|
| size | Size of the virtual memory region.|
| mmu_flags | MMU mapping attribute of the virtual memory region.|
| pages | Number of used physical pages, including that of the shared memory.|
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p986mcpsimp"><aname="p986mcpsimp"></a><aname="p986mcpsimp"></a>Specifies the number of times that the specified command is executed.</p>
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p995mcpsimp"><aname="p995mcpsimp"></a><aname="p995mcpsimp"></a>Specifies the interval (in seconds) for periodically running the specified command.</p>
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p1004mcpsimp"><aname="p1004mcpsimp"></a><aname="p1004mcpsimp"></a>Disables time display on the top.</p>
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p1013mcpsimp"><aname="p1013mcpsimp"></a><aname="p1013mcpsimp"></a>Specifies the command to be monitored.</p>
<tdclass="cellrowborder"valign="top"width="29.222922292229224%"headers="mcps1.2.5.1.2 "><pid="p1022mcpsimp"><aname="p1022mcpsimp"></a><aname="p1022mcpsimp"></a>Stops the current command monitoring.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1066mcpsimp"><aname="p1066mcpsimp"></a><aname="p1066mcpsimp"></a>Specifies the file path.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p1104mcpsimp"><aname="p1104mcpsimp"></a><aname="p1104mcpsimp"></a>Specifies the target file path.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p1106mcpsimp"><aname="p1106mcpsimp"></a><aname="p1106mcpsimp"></a>You must have the execution (search) permission for the specified directory.</p>
</td>
</tr>
</tbody>
</table>
## Parameters
## Usage<a name="section3629759111317"></a>
**Table 1** Parameter description
- If **path** is not specified, this command switches to the root directory.
- If **path** is specified, this command switches to the specified directory.
- The **path** value starting with a slash \(/\) represents the root directory.
- The **path** value starting with a dot \(.\) represents the current directory.
- The **path** value starting with two dots \(..\) represents the parent directory.
- You can run **cd -** to alternate between two directories that are recently accessed.
| Parameter| Description| Value Range|
| -------- | -------- | -------- |
| path | Specifies the path of the new directory. | You must have the execution (search) permission on the specified directory.|
## Example<a name="section211620301412"></a>
Run **cd ..**.
## Usage Guidelines
## Output<a name="section1968117214577"></a>
- If **path** is not specified, this command switches to the root directory.
- If **path** is specified, this command switches to the specified directory.
- The **path** value starting with a slash (/) represents the root directory.
- The **path** value starting with a dot (.) represents the current directory.
- The **path** value starting with two dots (..) represents the parent directory.
- You can run **cd -** to alternate between two directories that are recently accessed.
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p4218826194210"><aname="p4218826194210"></a><aname="p4218826194210"></a>Specifies the file path.</p>
| mode | Specifies the permissions for a file or directory. The value is an octal number, representing the permission of **User** (owner), **Group** (group), or **Others** (other groups).| [0, 777] |
| filename | Specifies the file path. | An existing file |
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p3911344161713"><aname="p3911344161713"></a><aname="p3911344161713"></a>Specifies the permissions for a file or directory. The value is an octal number, representing the permission of <strongid="b11602834153114"><aname="b11602834153114"></a><aname="b11602834153114"></a>User</strong> (owner), <strongid="b032113853120"><aname="b032113853120"></a><aname="b032113853120"></a>Group</strong> (group), or <strongid="b1980114418310"><aname="b1980114418310"></a><aname="b1980114418310"></a>Others</strong> (other groups).</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p149134481719"><aname="p149134481719"></a><aname="p149134481719"></a>Specifies the file name.</p>
- For the files created on the FAT file system, the file permission attributes are the same as those of the mounted nodes. Currently, the node permissions include only user read and write. The **group** and **others** permissions do not take effect. In addition, only the user read and write permissions can be modified. The read and write permissions are **rw** and **ro** only. There is no such restriction for other file systems.
- For the files created on the FAT file system, the file permission attributes are the same as those of the mounted nodes. Currently, the node permissions include only user read and write. The **group** and **others** permissions do not take effect. In addition, only the user read and write permissions can be modified. The read and write permissions are **rw** and **ro** only. There is no such restriction for other file systems.
## Example<a name="section8518195718147"></a>
## Note
Change the permissions on the **hello-harmony.txt** file to **644** and **777**.
Currently, the shell does not support this command.
## Output<a name="section127391818158"></a>
## Example
Modifying the permissions on the **hello-harmony.txt** file in the **/dev** directory:
Change the permissions on the **hello-openharmony.txt** file to **644** and **777**.
## Output
Modify the permissions on the **hello-openharmony.txt** file in the **/dev** directory.
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p14126172111"><aname="p14126172111"></a><aname="p14126172111"></a>Specifies the file owner.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p7412315218"><aname="p7412315218"></a><aname="p7412315218"></a>Specifies the file path.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p181687882317"><aname="p181687882317"></a><aname="p181687882317"></a>Displays help information.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p81686862314"><aname="p81686862314"></a><aname="p81686862314"></a>Specifies the path of the source file.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p1016811862312"><aname="p1016811862312"></a><aname="p1016811862312"></a>This command does not support copy of a directory, but supports copy of multiple files at a time.</p>
<tdclass="cellrowborder"valign="top"width="52%"headers="mcps1.2.4.1.2 "><pid="p9168789231"><aname="p9168789231"></a><aname="p9168789231"></a>Specifies the destination file path.</p>
</td>
<tdclass="cellrowborder"valign="top"width="27%"headers="mcps1.2.4.1.3 "><pid="p316810810235"><aname="p316810810235"></a><aname="p316810810235"></a>Both a directory and a file are supported.</p>
</td>
</tr>
</tbody>
</table>
## Usage<a name="section16128156162"></a>
- The name of the source file cannot be the same as that of the destination file in the same path.
-**SOURCEFILE** must exist and cannot be a directory.
-**SOURCEFILE** supports wildcard characters \* and ?. The asterisk \(\*\) indicates any number of characters, and the question mark \(?\) represents a single character. **DESTFILE** does not support wildcard characters. If **SOURCEFILE** specifies multiple files, **DESTFILE** must be a directory.
- If **DESTFILE** specifies a directory, this directory must exist. In this case, the destination file is named after the source file.
- If **DESTFILE** specifies a file, the directory for this file must exist. In this case, the file copy is renamed.
- If the destination file does not exist, a new file is created. If the destination file already exists, the existing file is overwritten.
>When important system resources are copied, unexpected results such as a system breakdown may occur. For example, when the **/dev/uartdev-1** file is copied, the system may stop responding.
## Example<a name="section19354171211618"></a>
Run **cp hello-OHOS.txt hello-harmony.txt ./tmp/**.
## Output<a name="section16754183195914"></a>
Copying **hello-OHOS.txt** and **hello-harmony.txt** to **/tmp/**:
## Syntax
cp [_SOURCEFILE_] [_DESTFILE_]
## Parameters
**Table 1** Parameter description
| Parameter| Description| Value Range|
| -------- | -------- | -------- |
| --help | Displays help information.| N/A |
| SOURCEFILE | Specifies the file to copy.| This command does not support copy of a directory, but supports copy of multiple files at a time.|
| DESTFILE | Specifies the file to create.| Both a directory and a file are supported.|
## Usage Guidelines
- The name of the source file cannot be the same as that of the destination file in the same path.
-**SOURCEFILE** must exist and cannot be a directory.
- The source file path supports asterisks (*) and question marks (?). The wildcard "\*" indicates any number of characters, and "?" indicates any single character. **DEST** does not support wildcard characters. If the specified **SOURCE** matches multiple files, **DEST** must be a directory.
- If **DEST** is a directory, this directory must exist. In this case, the destination file is named after the source file.
- If the destination file path is a file, the directory for this file must exist. In this case, the file copy is renamed.
- If the destination file does not exist, a new file is created. If the destination file already exists, the existing file is overwritten.
> **NOTICE**<br>
> When important system resources are copied, unexpected results such as a system breakdown may occur. For example, when the **/dev/uartdev-1** file is copied, the system may stop responding.
## Example
Run **cp hello-OHOS.txt hello-openharmony.txt ./tmp/**.
## Output
Copy **hello-OHOS.txt** and **hello-openharmony.txt** to **/tmp/**.
<tdclass="cellrowborder"valign="top"width="66%"headers="mcps1.2.3.1.2 "><pid="p1197mcpsimp"><aname="p1197mcpsimp"></a><aname="p1197mcpsimp"></a>Specifies the device name.</p>
<tdclass="cellrowborder"valign="top"width="66%"headers="mcps1.2.3.1.2 "><pid="p1207mcpsimp"><aname="p1207mcpsimp"></a><aname="p1207mcpsimp"></a>Specifies the size of the allocated memory unit or sector. The value <strongid="b1574273871018"><aname="b1574273871018"></a><aname="b1574273871018"></a>0</strong> indicates null. (The value must be <strongid="b16428721113"><aname="b16428721113"></a><aname="b16428721113"></a>0</strong> or a power of <strongid="b1053419931111"><aname="b1053419931111"></a><aname="b1053419931111"></a>2</strong>. For FAT32, the maximum value is <strongid="b51473841110"><aname="b51473841110"></a><aname="b51473841110"></a>128</strong>. If the parameter is set to <strongid="b99547931214"><aname="b99547931214"></a><aname="b99547931214"></a>0</strong>, a proper cluster size is automatically selected. The available cluster size range varies depending on the partition size. If the cluster size is incorrectly specified, the formatting may fail.)</p>
<tdclass="cellrowborder"valign="top"width="66%"headers="mcps1.2.3.1.2 "><divclass="p"id="p1212mcpsimp"><aname="p1212mcpsimp"></a><aname="p1212mcpsimp"></a>Specifies the file system type. The options are as follows:<aname="ul10971366369"></a><aname="ul10971366369"></a><ulid="ul10971366369"><li><strongid="b169384514517"><aname="b169384514517"></a><aname="b169384514517"></a>0x01</strong>: FMT_FAT</li><li><strongid="b143061510125114"><aname="b143061510125114"></a><aname="b143061510125114"></a>0x02</strong>: FMT_FAT32</li><li><strongid="b3245614165116"><aname="b3245614165116"></a><aname="b3245614165116"></a>0x07</strong>: FMT_ANY</li><li><strongid="b018121813512"><aname="b018121813512"></a><aname="b018121813512"></a>0x08</strong>: FMT_ERASE (not supported by the USB flash drive)</li></ul>
</div>
<pid="p28366459374"><aname="p28366459374"></a><aname="p28366459374"></a>If an invalid value is specified, the system automatically selects the formatting mode. If the low-level formatting bit is <strongid="b4634562520"><aname="b4634562520"></a><aname="b4634562520"></a>1</strong> during the formatting of a USB flash drive, an error message is printed.</p>
<tdclass="cellrowborder"valign="top"width="66%"headers="mcps1.2.3.1.2 "><pid="p1217mcpsimp"><aname="p1217mcpsimp"></a><aname="p1217mcpsimp"></a>Specifies the volume label name. This parameter is optional, and the value is a string. If <strongid="b16648426102713"><aname="b16648426102713"></a><aname="b16648426102713"></a>null</strong> is specified for this parameter, the previously set volume label name is cleared.</p>
</td>
</tr>
</tbody>
</table>
## Usage<a name="section1510162714162"></a>
- The **format** command is used for disk formatting. You can find the device name in the **dev** directory. A storage card must be installed before the formatting.
- The **format** command can be used to format the USB flash drive, SD card, and MMC, but not the NAND flash or NOR flash.
- An invalid **sectors** value may cause exceptions.
## Example<a name="section25691431161611"></a>
Run **format /dev/mmcblk0 128 2**.
## Output<a name="section17368112365920"></a>
Formatting an MMC:
## Syntax
format <*dev*inodename_><*sectors*><*option*> [_label_]
## Parameters
**Table 1** Parameter description
| Parameter| Description|
| -------- | -------- |
| dev_inodename | Specifies the device name. |
| sectors | Specifies the size of the allocated memory unit or sector. <br/>The value must be **0** or a power of **2**.<br/>The value **0** means to leave this parameter blank. <br/>For FAT32, the maximum value is **128**. If the parameter is set to **0**, a proper cluster size is automatically selected. The available cluster size range varies depending on the partition size. If the cluster size is incorrectly specified, the formatting may fail. |
| option | Specifies the file system type. The options are as follows:<br>- **0x01**: FMT_FAT<br>- **0x02**: FMT_FAT32<br>- **0x07**: FMT_ANY<br>- **0x08**: FMT_ERASE (USB does not support this option.)<br>If an invalid value is specified, the system automatically selects the formatting mode. If the low-level formatting bit is **1** during the formatting of a USB flash drive, an error message is printed.|
| label | Specifies the volume label name. This parameter is optional, and the value is a string. <br/>If **null** is specified for this parameter, the previously set volume label name is cleared. |
## Usage Guidelines
- The **format** command is used for disk formatting. You can find the device name in the **dev** directory. A storage card must be installed before the formatting.
- The **format** command can be used to format the USB flash drive, SD card, and MMC, but not the NAND flash or NOR flash.
- An invalid **sectors** value may cause exceptions.
