home *** CD-ROM | disk | FTP | other *** search
/ Hackers Magazine 57 / CdHackersMagazineNr57.iso / Software / Hacking / OperaTor-3.4.exe / OperaTor / Tor / Documents / HACKING < prev    next >
Encoding:
Text File  |  2008-11-21  |  9.6 KB  |  261 lines
  1.  
  2. 0. The buildbot.
  3.  
  4.   http://tor-buildbot.freehaven.net:8010/
  5.  
  6.   - Down for unknown reasons, ioerror will look into this.
  7.  
  8. 0.1. Useful command-lines that are non-trivial to reproduce but can
  9. help with tracking bugs or leaks.
  10.  
  11. dmalloc -l ~/dmalloc.log
  12. (run the commands it tells you)
  13. ./configure --with-dmalloc
  14.  
  15. valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor
  16.  
  17. 0.2. Running gcov for unit test coverage
  18.  
  19.   make clean
  20.   make CFLAGS='-g -fprofile-arcs -ftest-coverage'
  21.   ./src/or/test
  22.   cd src/common; gcov *.[ch]
  23.   cd ../or; gcov *.[ch]
  24.  
  25.   Then, look at the .gcov files.  '-' before a line means that the
  26.   compiler generated  no code for that line.  '######' means that the
  27.   line was never reached.  Lines with numbers were called that number
  28.   of times.
  29.  
  30. 1. Coding conventions
  31.  
  32. 1.0. Whitespace and C conformance
  33.  
  34.   Invoke "make check-spaces" from time to time, so it can tell you about
  35.   deviations from our C whitespace style.  Generally, we use:
  36.     - Unix-style line endings
  37.     - K&R-style indentation
  38.     - No space before newlines
  39.     - A blank line at the end of each file
  40.     - Never more than one blank line in a row
  41.     - Always spaces, never tabs
  42.     - No more than 79-columns per line.
  43.     - Two spaces per indent.
  44.     - A space between control keywords and their corresponding paren
  45.       "if (x)", "while (x)", and "switch (x)", never "if(x)", "while(x)", or
  46.       "switch(x)".
  47.     - A space between anything and an open brace.
  48.     - No space between a function name and an opening paren. "puts(x)", not
  49.       "puts (x)".
  50.     - Function declarations at the start of the line.
  51.  
  52.   We try hard to build without warnings everywhere.  In particular, if you're
  53.   using gcc, you should invoke the configure script with the option
  54.   "--enable-gcc-warnings".  This will give a bunch of extra warning flags to
  55.   the compiler, and help us find divergences from our preferred C style.
  56.  
  57. 1.0.1. Getting emacs to edit Tor source properly.
  58.  
  59.   Hi, folks!  Nick here.  I like to put the following snippet in my .emacs
  60.   file:
  61.     (add-hook 'c-mode-hook
  62.           (lambda ()
  63.             (font-lock-mode 1)
  64.             (set-variable 'show-trailing-whitespace t)
  65.  
  66.             (let ((fname (expand-file-name (buffer-file-name))))
  67.               (cond
  68.                ((string-match "^/home/nickm/src/libevent" fname)
  69.                 (set-variable 'indent-tabs-mode t)
  70.                 (set-variable 'c-basic-offset 4)
  71.                 (set-variable 'tab-width 4))
  72.                ((string-match "^/home/nickm/src/tor" fname)
  73.                 (set-variable 'indent-tabs-mode nil)
  74.                 (set-variable 'c-basic-offset 2))
  75.                ((string-match "^/home/nickm/src/openssl" fname)
  76.                 (set-variable 'indent-tabs-mode t)
  77.                 (set-variable 'c-basic-offset 8)
  78.                 (set-variable 'tab-width 8))
  79.             ))))
  80.  
  81.   You'll note that it defaults to showing all trailing whitespace.  The
  82.   "cond" test detects whether the file is one of a few C free software
  83.   projects that I often edit, and sets up the indentation level and tab
  84.   preferences to match what they want.
  85.  
  86.   If you want to try this out, you'll need to change the filename regex
  87.   patterns to match where you keep your Tor files.
  88.  
  89.   If you *only* use emacs to edit Tor, you could always just say:
  90.  
  91.     (add-hook 'c-mode-hook
  92.           (lambda ()
  93.             (font-lock-mode 1)
  94.             (set-variable 'show-trailing-whitespace t)
  95.             (set-variable 'indent-tabs-mode nil)
  96.             (set-variable 'c-basic-offset 2)))
  97.  
  98.   There is probably a better way to do this.  No, we are probably not going
  99.   to clutter the files with emacs stuff.
  100.  
  101. 1.1. Details
  102.  
  103.   Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their
  104.   generic equivalents.  (They always succeed or exit.)
  105.  
  106.   You can get a full list of the compatibility functions that Tor provides
  107.   by looking through src/common/util.h and src/common/compat.h.
  108.  
  109.   Use 'INLINE' instead of 'inline', so that we work properly on Windows.
  110.  
  111. 1.2. Calling and naming conventions
  112.  
  113.   Whenever possible, functions should return -1 on error and 0 on success.
  114.  
  115.   For multi-word identifiers, use lowercase words combined with
  116.   underscores. (e.g., "multi_word_identifier").  Use ALL_CAPS for macros and
  117.   constants.
  118.  
  119.   Typenames should end with "_t".
  120.  
  121.   Function names should be prefixed with a module name or object name.  (In
  122.   general, code to manipulate an object should be a module with the same
  123.   name as the object, so it's hard to tell which convention is used.)
  124.  
  125.   Functions that do things should have imperative-verb names
  126.   (e.g. buffer_clear, buffer_resize); functions that return booleans should
  127.   have predicate names (e.g. buffer_is_empty, buffer_needs_resizing).
  128.  
  129. 1.3. What To Optimize
  130.  
  131.   Don't optimize anything if it's not in the critical path.  Right now,
  132.   the critical path seems to be AES, logging, and the network itself.
  133.   Feel free to do your own profiling to determine otherwise.
  134.  
  135. 1.4. Log conventions
  136.  
  137.   http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#LogLevels
  138.  
  139.   No error or warning messages should be expected during normal OR or OP
  140.   operation.
  141.  
  142.   If a library function is currently called such that failure always
  143.   means ERR, then the library function should log WARN and let the caller
  144.   log ERR.
  145.  
  146.   [XXX Proposed convention: every message of severity INFO or higher should
  147.   either (A) be intelligible to end-users who don't know the Tor source; or
  148.   (B) somehow inform the end-users that they aren't expected to understand
  149.   the message (perhaps with a string like "internal error").  Option (A) is
  150.   to be preferred to option (B). -NM]
  151.  
  152. 1.5. Doxygen
  153.  
  154.   We use the 'doxygen' utility to generate documentation from our
  155.   source code. Here's how to use it:
  156.  
  157.   1. Begin every file that should be documented with
  158.          /**
  159.           * \file filename.c
  160.           * \brief Short description of the file.
  161.           **/
  162.  
  163.      (Doxygen will recognize any comment beginning with /** as special.)
  164.  
  165.   2. Before any function, structure, #define, or variable you want to
  166.      document, add a comment of the form:
  167.  
  168.         /** Describe the function's actions in imperative sentences.
  169.          *
  170.          * Use blank lines for paragraph breaks
  171.          *   - and
  172.          *   - hyphens
  173.          *   - for
  174.          *   - lists.
  175.          *
  176.          * Write <b>argument_names</b> in boldface.
  177.          *
  178.          * \code
  179.          *     place_example_code();
  180.          *     between_code_and_endcode_commands();
  181.          * \endcode
  182.          */
  183.  
  184.   3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
  185.      "\>", "\\", "\%", and "\#".
  186.  
  187.   4. To document structure members, you can use two forms:
  188.  
  189.        struct foo {
  190.          /** You can put the comment before an element; */
  191.          int a;
  192.          int b; /**< Or use the less-than symbol to put the comment
  193.                  * after the element. */
  194.        };
  195.  
  196.   5. To generate documentation from the Tor source code, type:
  197.  
  198.      $ doxygen -g
  199.  
  200.      To generate a file called 'Doxyfile'.  Edit that file and run
  201.      'doxygen' to generate the API documentation.
  202.  
  203.   6. See the Doxygen manual for more information; this summary just
  204.      scratches the surface.
  205.  
  206. 2. Code notes
  207.  
  208. 2.1. Dataflows
  209.  
  210. 2.1.1. How Incoming data is handled
  211.  
  212. There are two paths for data arriving at Tor over the network: regular
  213. TCP data, and DNS.
  214.  
  215. 2.1.1.1. TCP.
  216.  
  217. When Tor takes information over the network, it uses the functions
  218. read_to_buf() and read_to_buf_tls() in buffers.c.  These read from a
  219. socket or an SSL* into a buffer_t, which is an mbuf-style linkedlist
  220. of memory chunks.
  221.  
  222. read_to_buf() and read_to_buf_tls() are called only from
  223. connection_read_to_buf() in connection.c.  It takes a connection_t
  224. pointer, and reads data into it over the network, up to the
  225. connection's current bandwidth limits.  It places that data into the
  226. "inbuf" field of the connection, and then:
  227.   - Adjusts the connection's want-to-read/want-to-write status as
  228.     appropriate.
  229.   - Increments the read and written counts for the connection as
  230.     appropriate.
  231.   - Adjusts bandwidth buckets as appropriate.
  232.  
  233. connection_read_to_buf() is called only from connection_handle_read().
  234. The connection_handle_read() function is called whenever libevent
  235. decides (based on select, poll, epoll, kqueue, etc) that there is data
  236. to read from a connection.  If any data is read,
  237. connection_handle_read() calls connection_process_inbuf() to see if
  238. any of the data can be processed.  If the connection was closed,
  239. connection_handle_read() calls connection_reached_eof().
  240.  
  241. Connection_process_inbuf() and connection_reached_eof() both dispatch
  242. based on the connection type to determine what to do with the data
  243. that's just arrived on the connection's inbuf field.  Each type of
  244. connection has its own version of these functions.  For example,
  245. directory connections process incoming data in
  246. connection_dir_process_inbuf(), while OR connections process incoming
  247. data in connection_or_process_inbuf().  These
  248. connection_*_process_inbuf() functions extract data from the
  249. connection's inbuf field (a buffer_t), using functions from buffers.c.
  250. Some of these accessor functions are straightforward data extractors
  251. (like fetch_from_buf()); others do protocol-specific parsing.
  252.  
  253.  
  254. 2.1.1.2. DNS
  255.  
  256. Tor launches (and optionally accepts) DNS requests using the code in
  257. eventdns.c, which is a copy of libevent's evdns.c.  (We don't use
  258. libevent's version because it is not yet in the versions of libevent
  259. all our users have.)  DNS replies are read in nameserver_read();
  260. DNS queries are read in server_port_read().
  261.