[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [tor/master] directory-level doxygen for "src/core"
commit e1cdca2e4f58c108539fe4c36205b16caca8d44f
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date: Mon Nov 4 16:28:28 2019 -0500
directory-level doxygen for "src/core"
---
doc/HACKING/design/03-modules.md | 89 -------------------------------------
src/core/core.dox | 12 +++++
src/core/crypto/core_crypto.dox | 6 ++-
src/core/mainloop/core_mainloop.dox | 10 ++++-
src/core/or/core_or.dox | 62 +++++++++++++++++++++++++-
src/core/proto/core_proto.dox | 6 ++-
6 files changed, 91 insertions(+), 94 deletions(-)
diff --git a/doc/HACKING/design/03-modules.md b/doc/HACKING/design/03-modules.md
index 93eb9d308..9ab2fa7da 100644
--- a/doc/HACKING/design/03-modules.md
+++ b/doc/HACKING/design/03-modules.md
@@ -1,95 +1,6 @@
## Tor's modules ##
-### Generic modules ###
-
-`buffers.c`
-: Implements the `buf_t` buffered data type for connections, and several
-low-level data handling functions to handle network protocols on it.
-
-`channel.c`
-: Generic channel implementation. Channels handle sending and receiving cells
-among tor nodes.
-
-`channeltls.c`
-: Channel implementation for TLS-based OR connections. Uses `connection_or.c`.
-
-`circuitbuild.c`
-: Code for constructing circuits and choosing their paths. (*Note*:
-this module could plausibly be split into handling the client side,
-the server side, and the path generation aspects of circuit building.)
-
-`circuitlist.c`
-: Code for maintaining and navigating the global list of circuits.
-
-`circuitmux.c`
-: Generic circuitmux implementation. A circuitmux handles deciding, for a
-particular channel, which circuit should write next.
-
-`circuitmux_ewma.c`
-: A circuitmux implementation based on the EWMA (exponentially
-weighted moving average) algorithm.
-
-`circuituse.c`
-: Code to actually send and receive data on circuits.
-
-`command.c`
-: Handles incoming cells on channels.
-
-`config.c`
-: Parses options from torrc, and uses them to configure the rest of Tor.
-
-`confparse.c`
-: Generic torrc-style parser. Used to parse torrc and state files.
-
-`connection.c`
-: Generic and common connection tools, and implementation for the simpler
-connection types.
-
-`connection_edge.c`
-: Implementation for entry and exit connections.
-
-`connection_or.c`
-: Implementation for OR connections (the ones that send cells over TLS).
-
-`main.c`
-: Principal entry point, main loops, scheduled events, and network
-management for Tor.
-
-`ntmain.c`
-: Implements Tor as a Windows service. (Not very well.)
-
-`onion.c`
-: Generic code for generating and responding to CREATE and CREATED
-cells, and performing the appropriate onion handshakes. Also contains
-code to manage the server-side onion queue.
-
-`onion_fast.c`
-: Implements the old SHA1-based CREATE_FAST/CREATED_FAST circuit
-creation handshake. (Now deprecated.)
-
-`onion_ntor.c`
-: Implements the Curve25519-based NTOR circuit creation handshake.
-
-`onion_tap.c`
-: Implements the old RSA1024/DH1024-based TAP circuit creation handshake. (Now
-deprecated.)
-
-`relay.c`
-: Handles particular types of relay cells, and provides code to receive,
-encrypt, route, and interpret relay cells.
-
-`scheduler.c`
-: Decides which channel/circuit pair is ready to receive the next cell.
-
-`statefile.c`
-: Handles loading and storing Tor's state file.
-
-`tor_main.c`
-: Contains the actual `main()` function. (This is placed in a separate
-file so that the unit tests can have their own `main()`.)
-
-
### Node-status modules ###
`directory.c`
diff --git a/src/core/core.dox b/src/core/core.dox
index b37c5e2d8..11bf55cb7 100644
--- a/src/core/core.dox
+++ b/src/core/core.dox
@@ -5,4 +5,16 @@
The "core" directory has the central protocols for Tor, which every
client and relay must implement in order to perform onion routing.
+It is divided into three lower-level pieces:
+
+ - \refdir{core/crypto} -- Tor-specific cryptography.
+
+ - \refdir{core/proto} -- Protocol encoding/decoding.
+
+ - \refdir{core/mainloop} -- A connection-oriented asynchronous mainloop.
+
+and one high-level piece:
+
+ - \refdir{core/or} -- Implements onion routing itself.
+
**/
diff --git a/src/core/crypto/core_crypto.dox b/src/core/crypto/core_crypto.dox
index 36c12371d..28ece92bb 100644
--- a/src/core/crypto/core_crypto.dox
+++ b/src/core/crypto/core_crypto.dox
@@ -1,4 +1,8 @@
/**
@dir /core/crypto
-@brief core/crypto
+@brief core/crypto: Tor-specific cryptography
+
+This module implements Tor's circuit-construction crypto and Tor's
+relay crypto.
+
**/
diff --git a/src/core/mainloop/core_mainloop.dox b/src/core/mainloop/core_mainloop.dox
index e97edde94..28cd42bf6 100644
--- a/src/core/mainloop/core_mainloop.dox
+++ b/src/core/mainloop/core_mainloop.dox
@@ -1,4 +1,12 @@
/**
@dir /core/mainloop
-@brief core/mainloop
+@brief core/mainloop: Non-onion-routing mainloop functionality
+
+This module uses the event-loop code of \refdir{lib/evloop} to implement an
+asynchronous connection-oriented protocol handler.
+
+The layering here is imperfect: the code here was split from \refdir{core/or}
+without refactoring how the two modules call one another. Probably many
+functions should be moved and refactored.
+
**/
diff --git a/src/core/or/core_or.dox b/src/core/or/core_or.dox
index 754690e00..705e9b543 100644
--- a/src/core/or/core_or.dox
+++ b/src/core/or/core_or.dox
@@ -1,4 +1,62 @@
/**
@dir /core/or
-@brief core/or
-**/
+@brief core/or: *Onion routing happens here*.
+
+This is the central part of Tor that handles the core tasks of onion routing:
+building circuit, handling circuits, attaching circuit to streams, moving
+data around, and so forth.
+
+Some aspects of this module should probably be refactored into others.
+
+Notable files here include:
+
+`channel.c`
+: Generic channel implementation. Channels handle sending and receiving cells
+among tor nodes.
+
+`channeltls.c`
+: Channel implementation for TLS-based OR connections. Uses `connection_or.c`.
+
+`circuitbuild.c`
+: Code for constructing circuits and choosing their paths. (*Note*:
+this module could plausibly be split into handling the client side,
+the server side, and the path generation aspects of circuit building.)
+
+`circuitlist.c`
+: Code for maintaining and navigating the global list of circuits.
+
+`circuitmux.c`
+: Generic circuitmux implementation. A circuitmux handles deciding, for a
+particular channel, which circuit should write next.
+
+`circuitmux_ewma.c`
+: A circuitmux implementation based on the EWMA (exponentially
+weighted moving average) algorithm.
+
+`circuituse.c`
+: Code to actually send and receive data on circuits.
+
+`command.c`
+: Handles incoming cells on channels.
+
+`connection.c`
+: Generic and common connection tools, and implementation for the simpler
+connection types.
+
+`connection_edge.c`
+: Implementation for entry and exit connections.
+
+`connection_or.c`
+: Implementation for OR connections (the ones that send cells over TLS).
+
+`onion.c`
+: Generic code for generating and responding to CREATE and CREATED
+cells, and performing the appropriate onion handshakes. Also contains
+code to manage the server-side onion queue.
+
+`relay.c`
+: Handles particular types of relay cells, and provides code to receive,
+encrypt, route, and interpret relay cells.
+
+`scheduler.c`
+: Decides which channel/circuit pair is ready to receive the next cell.
diff --git a/src/core/proto/core_proto.dox b/src/core/proto/core_proto.dox
index 2e92a6513..13ce751a7 100644
--- a/src/core/proto/core_proto.dox
+++ b/src/core/proto/core_proto.dox
@@ -1,4 +1,8 @@
/**
@dir /core/proto
-@brief core/proto
+@brief core/proto: Protocol encoding/decoding
+
+These functions should (but do not always) exist at a lower level than most
+of the rest of core.
+
**/
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits