diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-09-18 01:22:26 +0200 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-09-18 01:22:26 +0200 |
commit | 7c672abc120a55f678e5571ae2ee93f06ca4d7f9 (patch) | |
tree | 7beebc09f9626ca8d5f7df4dded0a553de479323 /Documentation/w1/w1-netlink.rst | |
parent | Merge branch 'for-5.4' of git://git.kernel.org/pub/scm/linux/kernel/git/denni... (diff) | |
parent | Documentation: kbuild: Add document about reproducible builds (diff) | |
download | linux-7c672abc120a55f678e5571ae2ee93f06ca4d7f9.tar.xz linux-7c672abc120a55f678e5571ae2ee93f06ca4d7f9.zip |
Merge tag 'docs-5.4' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It's a somewhat calmer cycle for docs this time, as the churn of the
mass RST conversion is happily mostly behind us.
- A new document on reproducible builds.
- We finally got around to zapping the documentation for hardware
support that was removed in 2004; one doesn't want to rush these
things.
- The usual assortment of fixes, typo corrections, etc"
* tag 'docs-5.4' of git://git.lwn.net/linux: (67 commits)
Documentation: kbuild: Add document about reproducible builds
docs: printk-formats: Stop encouraging use of unnecessary %h[xudi] and %hh[xudi]
Documentation: Add "earlycon=sbi" to the admin guide
doc:lock: remove reference to clever use of read-write lock
devices.txt: improve entry for comedi (char major 98)
docs: mtd: Update spi nor reference driver
doc: arm64: fix grammar dtb placed in no attributes region
Documentation: sysrq: don't recommend 'S' 'U' before 'B'
mailmap: Update email address for Quentin Perret
docs: ftrace: clarify when tracing is disabled by the trace file
docs: process: fix broken link
Documentation/arm/samsung-s3c24xx: Remove stray U+FEFF character to fix title
Documentation/arm/sa1100/assabet: Fix 'make assabet_defconfig' command
Documentation/arm/sa1100: Remove some obsolete documentation
docs/zh_CN: update Chinese howto.rst for latexdocs making
Documentation: virt: Fix broken reference to virt tree's index
docs: Fix typo on pull requests guide
kernel-doc: Allow anonymous enum
Documentation: sphinx: Don't parse socket() as identifier reference
Documentation: sphinx: Add missing comma to list of strings
...
Diffstat (limited to 'Documentation/w1/w1-netlink.rst')
-rw-r--r-- | Documentation/w1/w1-netlink.rst | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/Documentation/w1/w1-netlink.rst b/Documentation/w1/w1-netlink.rst new file mode 100644 index 000000000000..aaa13243a5e4 --- /dev/null +++ b/Documentation/w1/w1-netlink.rst @@ -0,0 +1,202 @@ +=============================================== +Userspace communication protocol over connector +=============================================== + +Message types +============= + +There are three types of messages between w1 core and userspace: + +1. Events. They are generated each time a new master or slave device + is found either due to automatic or requested search. +2. Userspace commands. +3. Replies to userspace commands. + + +Protocol +======== + +:: + + [struct cn_msg] - connector header. + Its length field is equal to size of the attached data + [struct w1_netlink_msg] - w1 netlink header. + __u8 type - message type. + W1_LIST_MASTERS + list current bus masters + W1_SLAVE_ADD/W1_SLAVE_REMOVE + slave add/remove events + W1_MASTER_ADD/W1_MASTER_REMOVE + master add/remove events + W1_MASTER_CMD + userspace command for bus master + device (search/alarm search) + W1_SLAVE_CMD + userspace command for slave device + (read/write/touch) + __u8 status - error indication from kernel + __u16 len - size of data attached to this header data + union { + __u8 id[8]; - slave unique device id + struct w1_mst { + __u32 id; - master's id + __u32 res; - reserved + } mst; + } id; + + [struct w1_netlink_cmd] - command for given master or slave device. + __u8 cmd - command opcode. + W1_CMD_READ - read command + W1_CMD_WRITE - write command + W1_CMD_SEARCH - search command + W1_CMD_ALARM_SEARCH - alarm search command + W1_CMD_TOUCH - touch command + (write and sample data back to userspace) + W1_CMD_RESET - send bus reset + W1_CMD_SLAVE_ADD - add slave to kernel list + W1_CMD_SLAVE_REMOVE - remove slave from kernel list + W1_CMD_LIST_SLAVES - get slaves list from kernel + __u8 res - reserved + __u16 len - length of data for this command + For read command data must be allocated like for write command + __u8 data[0] - data for this command + + +Each connector message can include one or more w1_netlink_msg with +zero or more attached w1_netlink_cmd messages. + +For event messages there are no w1_netlink_cmd embedded structures, +only connector header and w1_netlink_msg strucutre with "len" field +being zero and filled type (one of event types) and id: +either 8 bytes of slave unique id in host order, +or master's id, which is assigned to bus master device +when it is added to w1 core. + +Currently replies to userspace commands are only generated for read +command request. One reply is generated exactly for one w1_netlink_cmd +read request. Replies are not combined when sent - i.e. typical reply +messages looks like the following:: + + [cn_msg][w1_netlink_msg][w1_netlink_cmd] + cn_msg.len = sizeof(struct w1_netlink_msg) + + sizeof(struct w1_netlink_cmd) + + cmd->len; + w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; + w1_netlink_cmd.len = cmd->len; + +Replies to W1_LIST_MASTERS should send a message back to the userspace +which will contain list of all registered master ids in the following +format:: + + cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct + w1_netlink_msg) plus number of masters multiplied by 4) + w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to + number of masters multiplied by 4 (u32 size)) + id0 ... idN + +Each message is at most 4k in size, so if number of master devices +exceeds this, it will be split into several messages. + +W1 search and alarm search commands. + +request:: + + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] + +reply:: + + [cn_msg, ack = 1 and increasing, 0 means the last message, + seq is equal to the request seq] + [w1_netlink_msg type = W1_MASTER_CMD] + [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH + len is equal to number of IDs multiplied by 8] + [64bit-id0 ... 64bit-idN] + +Length in each header corresponds to the size of the data behind it, so +w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. +Can be zero. + +:: + + w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; + cn_msg->len = sizeof(struct w1_netlink_msg) + + sizeof(struct w1_netlink_cmd) + + N*8; + +W1 reset command:: + + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_RESET] + + +Command status replies +====================== + +Each command (either root, master or slave with or without w1_netlink_cmd +structure) will be 'acked' by the w1 core. Format of the reply is the same +as request message except that length parameters do not account for data +requested by the user, i.e. read/write/touch IO requests will not contain +data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size +of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum +of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd). +If reply is generated for master or root command (which do not have +w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg +structures. + +w1_netlink_msg.status field will carry positive error value +(EINVAL for example) or zero in case of success. + +All other fields in every structure will mirror the same parameters in the +request message (except lengths as described above). + +Status reply is generated for every w1_netlink_cmd embedded in the +w1_netlink_msg, if there are no w1_netlink_cmd structures, +reply will be generated for the w1_netlink_msg. + +All w1_netlink_cmd command structures are handled in every w1_netlink_msg, +even if there were errors, only length mismatch interrupts message processing. + + +Operation steps in w1 core when new command is received +======================================================= + +When new message (w1_netlink_msg) is received w1 core detects if it is +master or slave request, according to w1_netlink_msg.type field. +Then master or slave device is searched for. +When found, master device (requested or those one on where slave device +is found) is locked. If slave command is requested, then reset/select +procedure is started to select given device. + +Then all requested in w1_netlink_msg operations are performed one by one. +If command requires reply (like read command) it is sent on command completion. + +When all commands (w1_netlink_cmd) are processed master device is unlocked +and next w1_netlink_msg header processing started. + + +Connector [1] specific documentation +==================================== + +Each connector message includes two u32 fields as "address". +w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header. +Each message also includes sequence and acknowledge numbers. +Sequence number for event messages is appropriate bus master sequence number +increased with each event message sent "through" this master. +Sequence number for userspace requests is set by userspace application. +Sequence number for reply is the same as was in request, and +acknowledge number is set to seq+1. + + +Additional documentation, source code examples +============================================== + +1. Documentation/driver-api/connector.rst +2. http://www.ioremap.net/archive/w1 + + This archive includes userspace application w1d.c which uses + read/write/search commands for all master/slave devices found on the bus. |