Differences

This shows you the differences between two versions of the page.

--- en:users:drivers:ath10k:codingstyle [2018/04/12 13:37]
Kalle Valo Move Linux coding style and checking code sections to the beginning of the page
+++ en:users:drivers:ath10k:codingstyle [2024/04/30 05:50] (current)
Kalle Valo [Checking code] add links to ath11k-check and ath12k-check
@@ Line 5: / Line 5: @@
-===== ath10k Coding Style =====
+===== ath10k/ath11k/ath12k Coding Style =====
+==== Introduction ====
-==== Linux coding style ====
+This is the coding style document for [[en/users/Drivers/ath10k|ath10k]], [[en/users/Drivers/ath11k|ath11k]] and [[en/users/Drivers/ath12k|ath12k]] drivers. Read this before writing any code.
-ath10k mostly follows [[https://www.kernel.org/doc/html/latest/process/coding-style.html|Linux Coding Style]], so read that first.
+==== Tools =====
+Use latest GCC which you can download from [[https://mirrors.edge.kernel.org/pub/tools/crosstool/|crosstool]]. Setting it up is easy, unpack it to a directory and create a GNUmakefile in Linux sources top-level directory:
+<code>
+ARCH=x86
+CROSS_COMPILE=/opt/cross/gcc-13.2.0-nolibc/x86_64-linux/bin/x86_64-linux-
+export ARCH
+export CROSS_COMPILE
+</code>
+You will need [[https://docs.kernel.org/dev-tools/sparse.html#getting-sparse|the latest sparse from git]]. Linux distros usually have too old sparse and you will see wrong errors!
 ==== Checking code ====
-For checking the code we have a dedicated script [[https://github.com/qca/qca-swiss-army-knife/blob/master/tools/scripts/ath10k/ath10k-check|ath10k-check]] which runs various tests, including sparse and checkpatch. Run the script with ''--help'' to see the installation and usage instructions. Strongly recommended to run this before submitting patches as it can catch common problems. Example:
+For checking the code we have dedicated scripts for each driver:
+  * [[https://github.com/qca/qca-swiss-army-knife/blob/master/tools/scripts/ath10k/ath10k-check|ath10k-check]]
+  * [[https://github.com/qca/qca-swiss-army-knife/blob/master/tools/scripts/ath11k/ath11k-check|ath11k-check]]
+  * [[https://github.com/qca/qca-swiss-army-knife/blob/master/tools/scripts/ath12k/ath12k-check|ath12k-check]]
+They run various tests, including sparse and checkpatch. Run the script with ''--help'' to see the installation and usage instructions. ''--version'' shows version information for all dependencies, include that when reporting a problem.
+It is required to run the check script before submitting patches as it can catch common problems. There must not be any warnings!
+An example how to run the script:
 <code>
@@ Line 46: / Line 69: @@
 ~/ath$
 </code>
+==== Linux coding style ====
+ath10k/ath11k/ath12k mostly follows [[https://docs.kernel.org/process/coding-style.html|Linux Coding Style]], so read that first.
 ==== Status/error variables ====
@@ Line 70: / Line 97: @@
 <code>struct ath10k *ar = ptr;
-struct ath10k_pci *ar_sdio = ath10k_pci_priv(ar);</code>
+struct ath10k_pci *ar_pci = ath10k_pci_priv(ar);</code>
 For consistency always use the main context (struct ath10k *ar) as function parameter, don't use hif specific context.
@@ Line 105: / Line 132: @@
-<code>ath10k_warn("failed to associate peer STA %pM\n: %d",
+<code>ath10k_warn("failed to associate peer STA %pM: %d\n",
             sta->addr, ret);</code>
-Try to start the warning messages with the the verb "failed" if possible. Warning and error messages start with lower case.
+Try to start the warning messages with the verb "failed" if possible. Warning and error messages start with lower case.
 ath10k_warn() is used for errors where it might be possible to recover and ath10k_err() for errors when it's not possible to recover in any way.
-Dan Carpenters g+ post about error paths: [[https://plus.google.com/u/0/106378716002406849458/posts/dnanfhQ4mHQ|https://plus.google.com/u/0/106378716002406849458/posts/dnanfhQ4mHQ]]
+Dan Carpenter's post about error paths: [[https://staticthinking.wordpress.com/2022/04/28/free-the-last-thing-style/|https://staticthinking.wordpress.com/2022/04/28/free-the-last-thing-style/]]
@@ Line 125: / Line 152: @@
 Example:
+<code>int ath10k_mac_start(struct ath10k *ar)</code>
-<code>int ath10k_init_hw(struct ath10k *ar)</code>
+For each component use function names create/destroy for allocating and freeing something, register/unregister for initializing and cleaning up them afterwards and start/stop to temporarily pause something.
-For each component use function names create/destroy for allocating and freeing something, init/cleanup for initialising variables and cleaning up them afterwards and start/stop to temporarily pause something.
 Example:
@@ Line 133: / Line 160: @@
 <code>int ath10k_cfg80211_create(struct ath10k *ar)
+int ath10k_cfg80211_register(struct ath10k *ar)
 int ath10k_cfg80211_start(struct ath10k *ar)
 void ath10k_cfg80211_stop(struct ath10k *ar)
-void ath10k_cfg80211_destory(struct ath10k *ar)</code>
+int ath10k_cfg80211_unregister(struct ath10k *ar)
+void ath10k_cfg80211_destroy(struct ath10k *ar)</code>
 ==== Comments ====
@@ Line 146: / Line 175: @@
  */</code>
+==== Error messages ====
+For warning and error messages we have ath10k_warn() and ath10k_err().
+ath10k_warn() should be used when ath10k still continues to work, for example then some limit has been reached or an unknown event has been received. It's also rate limited.
+ath10k_err() should be used when a fatal error has been detected and ath10k will shut itself down, for example during driver initialization or firmware recover fails. It is NOT rate limited.
+Examples:
+  ath10k_warn(ar, "failed to submit frame %d: %d\n", frame_index, ret);
+  ath10k_err(ar, "failed to wake up the device from sleep: %d\n", ret);
+==== Debug messages ====
+Use ath10k_dbg() or ath10k_dbg_dump().
+The format string for ath10k_dbg() should start with debug level followed by name of the command or event and then parameters. All lowercase and no commas, colons or periods.
+Examples:
+<code>ath10k_dbg(ar, ATH10K_DBG_BOOT, "boot suspend complete\n");
+ath10k_dbg(ar, ATH10K_DBG_WMI, "wmi mgmt tx skb %pK len %d ftype %02x stype %02x\n",
+	   msdu, skb->len, fc & IEEE80211_FCTL_FTYPE,
+	   fc & IEEE80211_FCTL_STYPE);
+ath10k_dbg(ar, ATH10K_DBG_MAC, "mac update sta %pM peer bw %d\n",
+	   sta->addr, bw);
+</code>
 ==== Things NOT to do ====

Linux Wireless

User Tools

Site Tools

Differences

Page Tools