• Ahmed S. Darwish's avatar
    Documentation: locking: Describe seqlock design and usage · 0d24f65e
    Ahmed S. Darwish authored
    Proper documentation for the design and usage of sequence counters and
    sequential locks does not exist. Complete the seqlock.h documentation as
    follows:
    
      - Divide all documentation on a seqcount_t vs. seqlock_t basis. The
        description for both mechanisms was intermingled, which is incorrect
        since the usage constrains for each type are vastly different.
    
      - Add an introductory paragraph describing the internal design of, and
        rationale for, sequence counters.
    
      - Document seqcount_t writer non-preemptibility requirement, which was
        not previously documented anywhere, and provide a clear rationale.
    
      - Provide template code for seqcount_t and seqlock_t initialization
        and reader/writer critical sections.
    
      - Recommend using seqlock_t by default. It implicitly handles the
        serialization and non-preemptibility requirements of writers.
    
    At seqlock.h:
    
      - Remove references to brlocks as they've long been removed from the
        kernel.
    
      - Remove references to gcc-3.x since the kernel's minimum supported
        gcc version is 4.9.
    
    References: 0f6ed63b ("no need to keep brlock macros anymore...")
    References: 6ec4476a ("Raise gcc version requirement to 4.9")
    Signed-off-by: default avatarAhmed S. Darwish <a.darwish@linutronix.de>
    Signed-off-by: default avatarPeter Zijlstra (Intel) <peterz@infradead.org>
    Link: https://lkml.kernel.org/r/20200720155530.1173732-2-a.darwish@linutronix.de
    0d24f65e
seqlock.rst 5.14 KB