harmonize locking annotations

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

harmonize locking annotations

Anton Lindqvist-2
Hi,
I think we all agree that global locks should be represented using
uppercase letters in locking annotations. This is an attempt to
harmonize the existing annotations.

Comments? OK?

Index: dev/dt/dt_dev.c
===================================================================
RCS file: /cvs/src/sys/dev/dt/dt_dev.c,v
retrieving revision 1.7
diff -u -p -r1.7 dt_dev.c
--- dev/dt/dt_dev.c 27 Jun 2020 07:22:09 -0000 1.7
+++ dev/dt/dt_dev.c 29 Jun 2020 18:47:30 -0000
@@ -74,19 +74,19 @@
  *
  *  Locks used to protect struct members in this file:
  * m per-softc mutex
- * k kernel lock
+ * K kernel lock
  */
 struct dt_softc {
- SLIST_ENTRY(dt_softc) ds_next; /* [k] descriptor list */
+ SLIST_ENTRY(dt_softc) ds_next; /* [K] descriptor list */
  int ds_unit; /* [I] D_CLONE unique unit */
  pid_t ds_pid; /* [I] PID of tracing program */
 
  struct mutex ds_mtx;
 
- struct dt_pcb_list ds_pcbs; /* [k] list of enabled PCBs */
- struct dt_evt *ds_bufqueue; /* [k] copy evts to userland */
- size_t ds_bufqlen; /* [k] length of the queue */
- int ds_recording; /* [k] currently recording? */
+ struct dt_pcb_list ds_pcbs; /* [K] list of enabled PCBs */
+ struct dt_evt *ds_bufqueue; /* [K] copy evts to userland */
+ size_t ds_bufqlen; /* [K] length of the queue */
+ int ds_recording; /* [K] currently recording? */
  int ds_evtcnt; /* [m] # of readable evts */
 
  /* Counters */
@@ -94,7 +94,7 @@ struct dt_softc {
  uint64_t ds_dropevt; /* [m] # of events dropped */
 };
 
-SLIST_HEAD(, dt_softc) dtdev_list; /* [k] list of open /dev/dt nodes */
+SLIST_HEAD(, dt_softc) dtdev_list; /* [K] list of open /dev/dt nodes */
 
 /*
  * Probes are created during dt_attach() and never modified/freed during
@@ -104,7 +104,7 @@ unsigned int dt_nprobes; /* [I] # of p
 SIMPLEQ_HEAD(, dt_probe) dt_probe_list; /* [I] list of probes */
 
 struct rwlock dt_lock = RWLOCK_INITIALIZER("dtlk");
-volatile uint32_t dt_tracing = 0; /* [k] # of processes tracing */
+volatile uint32_t dt_tracing = 0; /* [K] # of processes tracing */
 
 void dtattach(struct device *, struct device *, void *);
 int dtopen(dev_t, int, int, struct proc *);
Index: dev/dt/dtvar.h
===================================================================
RCS file: /cvs/src/sys/dev/dt/dtvar.h,v
retrieving revision 1.3
diff -u -p -r1.3 dtvar.h
--- dev/dt/dtvar.h 28 Mar 2020 15:42:25 -0000 1.3
+++ dev/dt/dtvar.h 29 Jun 2020 18:47:30 -0000
@@ -159,14 +159,14 @@ int dtioc_req_isvalid(struct dtioc_req
  *
  *  Locks used to protect struct members in this file:
  * I immutable after creation
- * k kernel lock
- * k,s kernel lock for writting and SMR for reading
+ * K kernel lock
+ * K,S kernel lock for writting and SMR for reading
  * m per-pcb mutex
  * c owned (read & modified) by a single CPU
  */
 struct dt_pcb {
- SMR_SLIST_ENTRY(dt_pcb) dp_pnext; /* [k,s] next PCB per probe */
- TAILQ_ENTRY(dt_pcb) dp_snext; /* [k] next PCB per softc */
+ SMR_SLIST_ENTRY(dt_pcb) dp_pnext; /* [K,S] next PCB per probe */
+ TAILQ_ENTRY(dt_pcb) dp_snext; /* [K] next PCB per softc */
 
  /* Event states ring */
  unsigned int dp_prod; /* [m] read index */
@@ -203,18 +203,18 @@ void dt_pcb_ring_consume(struct dt_pcb
  *
  *  Locks used to protect struct members in this file:
  * I immutable after creation
- * k kernel lock
- * d dt_lock
- * d,s dt_lock for writting and SMR for reading
+ * K kernel lock
+ * D dt_lock
+ * D,S dt_lock for writting and SMR for reading
  */
 struct dt_probe {
- SIMPLEQ_ENTRY(dt_probe) dtp_next; /* [k] global list of probes */
- SMR_SLIST_HEAD(, dt_pcb) dtp_pcbs; /* [d,s] list of enabled PCBs */
+ SIMPLEQ_ENTRY(dt_probe) dtp_next; /* [K] global list of probes */
+ SMR_SLIST_HEAD(, dt_pcb) dtp_pcbs; /* [D,S] list of enabled PCBs */
  struct dt_provider *dtp_prov; /* [I] its to provider */
  const char *dtp_func; /* [I] probe function */
  const char *dtp_name; /* [I] probe name */
  uint32_t dtp_pbn; /* [I] unique ID */
- volatile uint32_t dtp_recording; /* [d] is it recording? */
+ volatile uint32_t dtp_recording; /* [D] is it recording? */
  uint8_t dtp_nargs; /* [I] # of arguments */
 
  /* Provider specific fields. */
@@ -228,7 +228,7 @@ struct dt_probe {
  */
 struct dt_provider {
  const char *dtpv_name; /* [I] provider name */
- volatile uint32_t dtpv_recording;/* [d] # of recording PCBs */
+ volatile uint32_t dtpv_recording;/* [D] # of recording PCBs */
 
  int (*dtpv_alloc)(struct dt_probe *, struct dt_softc *,
     struct dt_pcb_list *, struct dtioc_req *);
Index: kern/kern_tc.c
===================================================================
RCS file: /cvs/src/sys/kern/kern_tc.c,v
retrieving revision 1.59
diff -u -p -r1.59 kern_tc.c
--- kern/kern_tc.c 26 Jun 2020 18:48:31 -0000 1.59
+++ kern/kern_tc.c 29 Jun 2020 18:47:32 -0000
@@ -69,24 +69,24 @@ static struct timecounter dummy_timecoun
 /*
  * Locks used to protect struct members, global variables in this file:
  * I immutable after initialization
- * t tc_lock
- * w windup_mtx
+ * T tc_lock
+ * W windup_mtx
  */
 
 struct timehands {
  /* These fields must be initialized by the driver. */
- struct timecounter *th_counter; /* [w] */
- int64_t th_adjtimedelta; /* [tw] */
- int64_t th_adjustment; /* [w] */
- u_int64_t th_scale; /* [w] */
- u_int th_offset_count; /* [w] */
- struct bintime th_boottime; /* [tw] */
- struct bintime th_offset; /* [w] */
- struct bintime th_naptime; /* [w] */
- struct timeval th_microtime; /* [w] */
- struct timespec th_nanotime; /* [w] */
+ struct timecounter *th_counter; /* [W] */
+ int64_t th_adjtimedelta; /* [T,W] */
+ int64_t th_adjustment; /* [W] */
+ u_int64_t th_scale; /* [W] */
+ u_int th_offset_count; /* [W] */
+ struct bintime th_boottime; /* [T,W] */
+ struct bintime th_offset; /* [W] */
+ struct bintime th_naptime; /* [W] */
+ struct timeval th_microtime; /* [W] */
+ struct timespec th_nanotime; /* [W] */
  /* Fields not to be copied in tc_windup start with th_generation. */
- volatile u_int th_generation; /* [w] */
+ volatile u_int th_generation; /* [W] */
  struct timehands *th_next; /* [I] */
 };
 
@@ -109,8 +109,8 @@ struct rwlock tc_lock = RWLOCK_INITIALIZ
  */
 struct mutex windup_mtx = MUTEX_INITIALIZER(IPL_CLOCK);
 
-static struct timehands *volatile timehands = &th0; /* [w] */
-struct timecounter *timecounter = &dummy_timecounter; /* [t] */
+static struct timehands *volatile timehands = &th0; /* [W] */
+struct timecounter *timecounter = &dummy_timecounter; /* [T] */
 static SLIST_HEAD(, timecounter) tc_list = SLIST_HEAD_INITIALIZER(tc_list);
 
 /*
Index: kern/kern_timeout.c
===================================================================
RCS file: /cvs/src/sys/kern/kern_timeout.c,v
retrieving revision 1.72
diff -u -p -r1.72 kern_timeout.c
--- kern/kern_timeout.c 18 Feb 2020 12:13:40 -0000 1.72
+++ kern/kern_timeout.c 29 Jun 2020 18:47:32 -0000
@@ -47,12 +47,12 @@
  * Locks used to protect global variables in this file:
  *
  * I immutable after initialization
- * t timeout_mutex
+ * T timeout_mutex
  */
 struct mutex timeout_mutex = MUTEX_INITIALIZER(IPL_HIGH);
 
 void *softclock_si; /* [I] softclock() interrupt handle */
-struct timeoutstat tostat; /* [t] statistics and totals */
+struct timeoutstat tostat; /* [T] statistics and totals */
 
 /*
  * Timeouts are kept in a hierarchical timing wheel. The to_time is the value
@@ -64,9 +64,9 @@ struct timeoutstat tostat; /* [t] stati
 #define WHEELMASK 255
 #define WHEELBITS 8
 
-struct circq timeout_wheel[BUCKETS]; /* [t] Queues of timeouts */
-struct circq timeout_todo; /* [t] Due or needs scheduling */
-struct circq timeout_proc; /* [t] Due + needs process context */
+struct circq timeout_wheel[BUCKETS]; /* [T] Queues of timeouts */
+struct circq timeout_todo; /* [T] Due or needs scheduling */
+struct circq timeout_proc; /* [T] Due + needs process context */
 
 #define MASKWHEEL(wheel, time) (((time) >> ((wheel)*WHEELBITS)) & WHEELMASK)
 
Index: sys/filedesc.h
===================================================================
RCS file: /cvs/src/sys/sys/filedesc.h,v
retrieving revision 1.44
diff -u -p -r1.44 filedesc.h
--- sys/filedesc.h 30 Jan 2020 15:33:04 -0000 1.44
+++ sys/filedesc.h 29 Jun 2020 18:47:32 -0000
@@ -64,15 +64,15 @@ struct kqueue;
  * a atomic operations
  * f fd_lock
  * f/w fd_lock when writing
- * k kernel lock
+ * K kernel lock
  * m fd_fplock
  */
 struct filedesc {
  struct file **fd_ofiles; /* [f/w,m] file structures for
  *     open files */
  char *fd_ofileflags; /* [f] per-process open file flags */
- struct vnode *fd_cdir; /* [k] current directory */
- struct vnode *fd_rdir; /* [k] root directory */
+ struct vnode *fd_cdir; /* [K] current directory */
+ struct vnode *fd_rdir; /* [K] root directory */
  int fd_nfiles; /* [f] number of open files allocated */
  int fd_openfd; /* [f] number of files currently open */
  u_int *fd_himap; /* [f] each bit points to 32 fds */
@@ -80,7 +80,7 @@ struct filedesc {
  int fd_lastfile; /* [f] high-water mark of fd_ofiles */
  int fd_freefile; /* [f] approx. next free file */
  u_short fd_cmask; /* [f/w] mask for file creation */
- u_short fd_refcnt; /* [k] reference count */
+ u_short fd_refcnt; /* [K] reference count */
  struct rwlock fd_lock; /* lock for the file descs */
  struct mutex fd_fplock; /* lock for reading fd_ofiles without
  * fd_lock */
Index: sys/proc.h
===================================================================
RCS file: /cvs/src/sys/sys/proc.h,v
retrieving revision 1.295
diff -u -p -r1.295 proc.h
--- sys/proc.h 28 Apr 2020 08:29:40 -0000 1.295
+++ sys/proc.h 29 Jun 2020 18:47:32 -0000
@@ -152,7 +152,7 @@ struct unveil;
  * a atomic operations
  * m this process' `ps_mtx'
  * p this process' `ps_lock'
- * r rlimit_lock
+ * R rlimit_lock
  */
 struct process {
  /*
@@ -235,7 +235,7 @@ struct process {
 
 /* The following fields are all copied upon creation in process_new. */
 #define ps_startcopy ps_limit
- struct plimit *ps_limit; /* [m,r] Process limits. */
+ struct plimit *ps_limit; /* [m,R] Process limits. */
  struct pgrp *ps_pgrp; /* Pointer to process group. */
  struct emul *ps_emul; /* Emulation information */
 
@@ -325,12 +325,12 @@ struct p_inentry {
 /*
  *  Locks used to protect struct members in this file:
  * I immutable after creation
- * s scheduler lock
+ * S scheduler lock
  * l read only reference, see lim_read_enter()
  * o owned (read/modified only) by this thread
  */
 struct proc {
- TAILQ_ENTRY(proc) p_runq; /* [s] current run/sleep queue */
+ TAILQ_ENTRY(proc) p_runq; /* [S] current run/sleep queue */
  LIST_ENTRY(proc) p_list; /* List of all threads. */
 
  struct process *p_p; /* [I] The process of this thread. */
@@ -347,8 +347,8 @@ struct proc {
 
  int p_flag; /* P_* flags. */
  u_char p_spare; /* unused */
- char p_stat; /* [s] S* process status. */
- u_char p_runpri; /* [s] Runqueue priority */
+ char p_stat; /* [S] S* process status. */
+ u_char p_runpri; /* [S] Runqueue priority */
  u_char p_descfd; /* if not 255, fdesc permits this fd */
 
  pid_t p_tid; /* Thread identifier. */
@@ -360,15 +360,15 @@ struct proc {
 
  /* scheduling */
  int p_cpticks; /* Ticks of cpu time. */
- const volatile void *p_wchan; /* [s] Sleep address. */
+ const volatile void *p_wchan; /* [S] Sleep address. */
  struct timeout p_sleep_to;/* timeout for tsleep() */
- const char *p_wmesg; /* [s] Reason for sleep. */
- fixpt_t p_pctcpu; /* [s] %cpu for this thread */
- u_int p_slptime; /* [s] Time since last blocked. */
+ const char *p_wmesg; /* [S] Reason for sleep. */
+ fixpt_t p_pctcpu; /* [S] %cpu for this thread */
+ u_int p_slptime; /* [S] Time since last blocked. */
  u_int p_uticks; /* Statclock hits in user mode. */
  u_int p_sticks; /* Statclock hits in system mode. */
  u_int p_iticks; /* Statclock hits processing intr. */
- struct cpu_info * volatile p_cpu; /* [s] CPU we're running on. */
+ struct cpu_info * volatile p_cpu; /* [S] CPU we're running on. */
 
  struct rusage p_ru; /* Statistics */
  struct tusage p_tu; /* accumulated times. */
@@ -387,9 +387,9 @@ struct proc {
 #define p_startcopy p_sigmask
  sigset_t p_sigmask; /* Current signal mask. */
 
- u_char p_slppri; /* [s] Sleeping priority */
- u_char p_usrpri; /* [s] Priority based on p_estcpu & ps_nice */
- u_int p_estcpu; /* [s] Time averaged val of p_cpticks */
+ u_char p_slppri; /* [S] Sleeping priority */
+ u_char p_usrpri; /* [S] Priority based on p_estcpu & ps_nice */
+ u_int p_estcpu; /* [S] Time averaged val of p_cpticks */
  int p_pledge_syscall; /* Cache of current syscall */
 
  struct ucred *p_ucred; /* [o] cached credentials */
Index: sys/timetc.h
===================================================================
RCS file: /cvs/src/sys/sys/timetc.h,v
retrieving revision 1.10
diff -u -p -r1.10 timetc.h
--- sys/timetc.h 26 Oct 2019 21:16:38 -0000 1.10
+++ sys/timetc.h 29 Jun 2020 18:47:32 -0000
@@ -48,8 +48,8 @@ typedef void timecounter_pps_t(struct ti
 /*
  * Locks used to protect struct members in this file:
  * I immutable after initialization
- * t tc_lock
- * w windup_mtx
+ * T tc_lock
+ * W windup_mtx
  */
 
 struct timecounter {
@@ -82,7 +82,7 @@ struct timecounter {
  /* Pointer to the timecounter's private parts. */
  SLIST_ENTRY(timecounter) tc_next; /* [I] */
  /* Pointer to the next timecounter. */
- int64_t tc_freq_adj; /* [tw] */
+ int64_t tc_freq_adj; /* [T,W] */
  /* Current frequency adjustment. */
  u_int64_t tc_precision; /* [I] */
  /* Precision of the counter.  Computed in tc_init(). */