OWN(9)

okay bestie, sit down, hydrate, put your phone on do-not-disturb, because we are reading own(9) — the page out of the Kernel Developer's Manual about the Dallas Semiconductor 1-Wire Network and Transport Interface. it's giving kernel plumbing but make it fashion ✨ no cap, this one's actually cute once you get past the first paragraph.

💖 NAME 💖

own, own_send_command, own_commmand_wait, own_self_command, own_acquire_bus, own crc, own_release_bus, OWN_ACQUIRE_BUS, OWN_CRC, OWN_RELEASE_BUS, OWN_SEND_COMMAND — that's the whole squad right there, the Dallas Semiconductor 1-Wire Network and Transport Interface.

and yes, <hotpink>we keep the spelling exactly as it is</hotpink>: own crc has a literal space in it, and own_commmand_wait really does have three m's. we do not fix the manpage. we love the manpage 🫶

---

📜 SYNOPSIS 📜

#include <sys/bus.h>
#include <dev/ow/own.h>

int
own_send_command(device_t pdev, struct ow_cmd *cmd);

int
own_command_wait(device_t pdev, struct ow_cmd *cmd);

int
own_self_command(device_t pdev, struct ow_cmd *cmd, uint8_t xpt_cmd);

int
own_acquire_bus(device_t pdev, int how);

int
own_release_bus(device_t pdev);

int
own_crc(device_t pdev, uint8_t *buffer, size_t len);

int
OWN_SEND_COMMAND(device_t ndev, device_t pdev, struct ow_cmd *cmd);

int
OWN_ACQUIRE_BUS(device_t ndev, device_t pdev, int how);

void
OWN_RELEASE_BUS(device_t ndev, device_t pdev);

uint8_t
OWN_CRC(device_t ndev, device_t pdev, uint8_t *buffer, size_t len);

---

🌈 DESCRIPTION 🌈

so the own interface is basically three little friend groups of functions, all here to help you talk to 1-Wire devices:

1. sending commands 📨
2. reserving the bus 🚌
3. making sure your data isn't lying to you 🕵️

the wrappers exist for the raw OWN kobj(9) interfaces, and bestie, you should use the wrappers — they're the safer ones. the kobj(9) ones are the feral versions. use the wrappers, fr fr.

🎀 Bus Commands 🎀

the 1-Wire bus has layers of access to the devices sitting on it (very onion, very shrek). the own functions hand you the network layer and the transport layer.

• the network layer decides whether the next command is for every device on the bus, or for one specific device. it also says what speed the link layer should use. main character decisions.
• struct ow_cmd is the little container that holds network access, speed, and timing info. it says what commands to send and whether or not we're reading data back. its members are:
• flags — flags that control how the structure gets interpreted. these are defined in <dev/ow/ow.h>:
  • OW_FLAG_OVERDRIVE — send xpt_cmd bytes and read xpt_read bytes at overdrive speed. zoom zoom 🏎️
  • OW_FLAG_READ_BIT — interpret xpt_read_len as bits to be read after xpt_cmd, instead of bytes.
• rom_cmd — the ROM command bytes to send.
• rom_len — how many ROM command bytes to send.
• rom_read_len — how many bytes to read after sending the ROM command.
• rom_read — the buffer for the bytes read after the ROM command.
• xpt_cmd — the transport command to send.
• xpt_len — the length of the transport command bytes to send. pass 0 if there's no transport command, bestie, it's fine.
• xpt_read_len — how many bytes to read after the xpt_cmd bytes go out. but if OW_FLAG_READ_BIT is set in flags, then this is the number of bits to read. bits get packed into bytes, obviously. slay.
• xpt_read — the buffer for the data that got read.

okay now the actual functions:

• own_command_wait() — grabs the 1-Wire bus (and waits if it has to, no drama), sends the command, then releases the bus. very "in and out, quick trip" energy.
• own_send_command() — sends the command without reserving the bus first. bold of you.
• pdev is the client device — that's the presentation layer device — the one sending the command. cmd describes the transaction you want to yeet onto the 1-Wire bus.
• own_self_command() — fills in cmd with a MATCH_ROM ROM command, the ROM address of pdev, and the xpt_cmd. it's the convenient lil shortcut for building directed commands. obsessed. 💅

🔒 Bus Reservation 🔒

the 1-Wire system has an advisory lock on the bus that presentation layer devices can use to coordinate access with each other.

heads up bestie: the locking is purely advisory at this time. it's a vibe, not a cage.

• own_acquire_bus() — reserves the bus. if how is OWN_WAIT, it waits indefinitely (iconic patience). if you pass OWN_DONTWAIT and another client owns the bus, it returns the error EWOULDBLOCK instead. 😭
• own_release_bus() — releases the bus. say thank you and let it go.

🧚 Data Integrity 🧚

• own_crc() — computes the 1-Wire standard CRC function over the data passed in buffer and len, and returns the result. it's the "are you sure about that" of the 1-Wire world, and honestly, we should all have one. 💜

🦋 Notes 🦋

the 1-Wire standard (Maxim AN937) defines layers that are akin to ISO networking layers. let's break it down:

• the lowest relevant layer is the link layer — it defines the polling windows and the timing of the signaling of the different modes.
• the network layer is built on top of the link layer, and it's used to address devices in a unicast or multicast manner.
• the transport layer defines the commands and responses from the devices.
• the presentation layer is the device-specific commands and actions used to control the specific 1-Wire devices on the bus.

and for real, real:

• these interfaces are implemented by the ow(4) device.
• presentation layer devices (the children of the newbus ow(4) device) should only call the functions described here. that's your lane, stay in it. 🫶
• the functionality provided by the owc(4) device (specifically the owll(9) interface) should only be called by the ow(4) driver. that's their lane, stay out of it.

---

✨ SEE ALSO ✨

• ow(4)
• owc(4)
• owll(9)
• https://pdfserv.maximintegrated.com/en/an/AN937.pdf

---

⚖️ LEGAL ⚖️

1-Wire is a registered trademark of Maxim Integrated Products, Inc. 🏷️

---

📅 HISTORY 📅

the own driver first appeared in FreeBSD 11.0. a whole era.

---

👑 AUTHORS 👑

the own device driver and this manual page were written by Warner Losh. the way that one person wrote the driver and the docs? main character energy, truly. 💖

---

and that's the whole page bestie — this one shipped as part of Debian, dated July 20, 2015, filed under OWN(9). go forth, talk to your 1-Wire devices responsibly, and remember: advisory locks are advisory. mwah. 💅🌸