^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) The Lockronomicon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Your guide to the ancient and twisted locking policies of the tty layer and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) the warped logic behind them. Beware all ye who read on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Line Discipline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Line disciplines are registered with tty_register_ldisc() passing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) discipline number and the ldisc structure. At the point of registration the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) discipline must be ready to use and it is possible it will get used before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) the call returns success. If the call returns an error then it won't get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) called. Do not re-use ldisc numbers as they are part of the userspace ABI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) and writing over an existing ldisc will cause demons to eat your computer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) After the return the ldisc data has been copied so you may free your own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) copy of the structure. You must not re-register over the top of the line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) discipline even with the same data or your computer again will be eaten by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) demons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) In order to remove a line discipline call tty_unregister_ldisc().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) In ancient times this always worked. In modern times the function will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) code manages the module counts this should not usually be a concern.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Heed this warning: the reference count field of the registered copies of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) tty_ldisc structure in the ldisc table counts the number of lines using this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) discipline. The reference count of the tty_ldisc structure within a tty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) counts the number of active users of the ldisc at this instant. In effect it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) counts the number of threads of execution within an ldisc method (plus those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) about to enter and exit although this detail matters not).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Line Discipline Methods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) TTY side interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) open() Called when the line discipline is attached to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) the terminal. No other call into the line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) discipline for this tty will occur until it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) completes successfully. Should initialize any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) state needed by the ldisc, and set receive_room
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) in the tty_struct to the maximum amount of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) the line discipline is willing to accept from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) driver with a single call to receive_buf().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Returning an error will prevent the ldisc from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) being attached. Can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) close() This is called on a terminal when the line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) discipline is being unplugged. At the point of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) execution no further users will enter the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ldisc code for this tty. Can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) hangup() Called when the tty line is hung up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) The line discipline should cease I/O to the tty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) No further calls into the ldisc code will occur.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) The return value is ignored. Can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) read() (optional) A process requests reading data from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) the line. Multiple read calls may occur in parallel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) and the ldisc must deal with serialization issues.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) If not defined, the process will receive an EIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) error. May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) write() (optional) A process requests writing data to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) line. Multiple write calls are serialized by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) tty layer for the ldisc. If not defined, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) process will receive an EIO error. May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) flush_buffer() (optional) May be called at any point between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) open and close, and instructs the line discipline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) to empty its input buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) set_termios() (optional) Called on termios structure changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) The caller passes the old termios data and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) current data is in the tty. Called under the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) termios semaphore so allowed to sleep. Serialized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) against itself only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) poll() (optional) Check the status for the poll/select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) calls. Multiple poll calls may occur in parallel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ioctl() (optional) Called when an ioctl is handed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) tty layer that might be for the ldisc. Multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) ioctl calls may occur in parallel. May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) compat_ioctl() (optional) Called when a 32 bit ioctl is handed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) to the tty layer that might be for the ldisc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Multiple ioctl calls may occur in parallel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Driver Side Interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) ^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) receive_buf() (optional) Called by the low-level driver to hand
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) a buffer of received bytes to the ldisc for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) processing. The number of bytes is guaranteed not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) to exceed the current value of tty->receive_room.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) All bytes must be processed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) receive_buf2() (optional) Called by the low-level driver to hand
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) a buffer of received bytes to the ldisc for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) processing. Returns the number of bytes processed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) If both receive_buf() and receive_buf2() are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) defined, receive_buf2() should be preferred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) write_wakeup() May be called at any point between open and close.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) The TTY_DO_WRITE_WAKEUP flag indicates if a call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) is needed but always races versus calls. Thus the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) ldisc must be careful about setting order and to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) handle unexpected calls. Must not sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The driver is forbidden from calling this directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) from the ->write call from the ldisc as the ldisc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) is permitted to call the driver write method from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) this function. In such a situation defer it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) dcd_change() Report to the tty line the current DCD pin status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) changes and the relative timestamp. The timestamp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) cannot be NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) Driver Access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) ^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Line discipline methods can call the following methods of the underlying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) hardware driver through the function pointers within the tty->driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) structure:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) write() Write a block of characters to the tty device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Returns the number of characters accepted. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) character buffer passed to this method is already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) in kernel space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) put_char() Queues a character for writing to the tty device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) If there is no room in the queue, the character is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) flush_chars() (Optional) If defined, must be called after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) queueing characters with put_char() in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) start transmission.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) write_room() Returns the numbers of characters the tty driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) will accept for queueing to be written.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) ioctl() Invoke device specific ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Expects data pointers to refer to userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Returns ENOIOCTLCMD for unrecognized ioctl numbers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) set_termios() Notify the tty driver that the device's termios
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) settings have changed. New settings are in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) tty->termios. Previous settings should be passed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) the "old" argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) The API is defined such that the driver should return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) the actual modes selected. This means that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) driver function is responsible for modifying any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) bits in the request it cannot fulfill to indicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) the actual modes being used. A device with no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) hardware capability for change (e.g. a USB dongle or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) virtual port) can provide NULL for this method.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) throttle() Notify the tty driver that input buffers for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) line discipline are close to full, and it should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) somehow signal that no more characters should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) sent to the tty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) unthrottle() Notify the tty driver that characters can now be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) sent to the tty without fear of overrunning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) input buffers of the line disciplines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) stop() Ask the tty driver to stop outputting characters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) to the tty device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) start() Ask the tty driver to resume sending characters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) to the tty device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) hangup() Ask the tty driver to hang up the tty device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) break_ctl() (Optional) Ask the tty driver to turn on or off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) BREAK status on the RS-232 port. If state is -1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) then the BREAK status should be turned on; if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) state is 0, then BREAK should be turned off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) If this routine is not implemented, use ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) TIOCSBRK / TIOCCBRK instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) wait_until_sent() Waits until the device has written out all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) characters in its transmitter FIFO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) send_xchar() Send a high-priority XON/XOFF character to the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) ^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) Line discipline methods have access to tty->flags field containing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) following interesting flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) TTY_THROTTLED Driver input is throttled. The ldisc should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) tty->driver->unthrottle() in order to resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) reception when it is ready to process more data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) write_wakeup() method in order to resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) transmission when it can accept more data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) to transmit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) TTY_IO_ERROR If set, causes all subsequent userspace read/write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) calls on the tty to fail, returning -EIO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) TTY_OTHER_CLOSED Device is a pty and the other side has closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) smaller chunks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) Locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) ^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) Callers to the line discipline functions from the tty layer are required to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) take line discipline locks. The same is true of calls from the driver side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) but not yet enforced.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) Three calls are now provided::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) ldisc = tty_ldisc_ref(tty);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) takes a handle to the line discipline in the tty and returns it. If no ldisc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) is currently attached or the ldisc is being closed and re-opened at this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) point then NULL is returned. While this handle is held the ldisc will not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) change or go away::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) tty_ldisc_deref(ldisc)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) Returns the ldisc reference and allows the ldisc to be closed. Returning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) reference takes away your right to call the ldisc functions until you take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) a new reference::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) ldisc = tty_ldisc_ref_wait(tty);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) Performs the same function as tty_ldisc_ref except that it will wait for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) ldisc change to complete and then return a reference to the new ldisc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) While these functions are slightly slower than the old code they should have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) minimal impact as most receive logic uses the flip buffers and they only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) need to take a reference when they push bits up through the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) fail in this situation if used within these functions. Ldisc and driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) code calling its own functions must be careful in this case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) Driver Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ======================= =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) open() Called when a device is opened. May sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) close() Called when a device is closed. At the point of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) return from this call the driver must make no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) further ldisc calls of any kind. May sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) write() Called to write bytes to the device. May not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) sleep. May occur in parallel in special cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) Because this includes panic paths drivers generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) shouldn't try and do clever locking here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) put_char() Stuff a single character onto the queue. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) driver is guaranteed following up calls to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) flush_chars.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) flush_chars() Ask the kernel to write put_char queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) write_room() Return the number of characters that can be stuffed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) into the port buffers without overflow (or less).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) The ldisc is responsible for being intelligent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) about multi-threading of write_room/write calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) ioctl() Called when an ioctl may be for the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) set_termios() Called on termios change, serialized against
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) itself by a semaphore. May sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) set_ldisc() Notifier for discipline change. At the point this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) is done the discipline is not yet usable. Can now
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) sleep (I think)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) throttle() Called by the ldisc to ask the driver to do flow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) control. Serialization including with unthrottle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) is the job of the ldisc layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) unthrottle() Called by the ldisc to ask the driver to stop flow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) stop() Ldisc notifier to the driver to stop output. As with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) throttle the serializations with start() are down
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) to the ldisc layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) start() Ldisc notifier to the driver to start output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) hangup() Ask the tty driver to cause a hangup initiated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) from the host side. [Can sleep ??]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) break_ctl() Send RS232 break. Can sleep. Can get called in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) parallel, driver must serialize (for now), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) with write calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) wait_until_sent() Wait for characters to exit the hardware queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) of the driver. Can sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) send_xchar() Send XON/XOFF and if possible jump the queue with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) it in order to get fast flow control responses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) Cannot sleep ??
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) ======================= =======================================================
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags