README: explain descriptor helpers

Signed-off-by: junka <[email protected]>

Author: junka

README.md

@@ -1,12 +1,20 @@
 # TS Analyze
 
-use basic rules from ISO 13818 and ETSI EN 300 468 to decode MPEG2 TS
+A TS packet start with 4 bytes header, total length could be 188, 192 or 204 bytes.
+Most system will use 188 bytes.
 
-use EN 300 743 to decode subtitle
-use ETS 300 706 to decide teletext
+Construct TS packets we will get PES/PSI packets. PSI is structured for search and
+other auxiliary functions. PES contains ES packets which could be audio or vedio
+streams.
 
-Pinrt descriptors for DVB/ATSC/ISDB standard.
+With this understanding, you can start decoding a TS stream or file now.
 
+
+Use basic rules from ISO 13818 and ETSI EN 300 468 to decode MPEG2 TS
+Use EN 300 743 to decode subtitle
+Use ETS 300 706 to decode teletext
+
+Print descriptors for DVB/ATSC/ISDB standard.
 Print PSI tables infomation and some other subsystem infomation
 
 
@@ -24,21 +32,21 @@ and then do ```make``` for both ways
 ```
 ./tsanalyze tsfile
 ```
-- support file and udp stream analyze
+- Support file and udp stream analyze
 ```
-./tsanalyze -f udp udp://url 
+./tsanalyze -f udp udp://url_of_stream
 ```
-`Ctrl + C` to stop and show received ts info 
+`Ctrl + C` to stop and show received ts information 
 
-- print table selected
+- Print table selected
 ```
 ./tsanalyze tsfile -s pat -s cat 
 ```
-- show stats about ts stream
+- Print stats about ts streams
  ```
  ./tsanalyze tsfile -S
  ```
 
 
 # descriptor
-not all descriptor implemented now, see ```doc/descriptor.md``` to add new descriptors
+Not all descriptor implemented now, see ```doc/descriptor.md``` to add new descriptors

doc/descriptor.md

@@ -12,10 +12,39 @@ typedef struct descriptor
 A basic descriptor should have a structure with TLV like above.
 A descriptor is a list node. As descriptors can be chained in a table.
 
-Deine sevaral MACROs as helpers to expand the struct, parse the ts sections,
+Define sevaral MACROs as helpers to expand the struct, parse the ts sections,
 dump the result and free the list.
+For example, this expands definitions of a struct:
 ```
-__m(type, member, bits)
-__m1(type, member)
-__mplast(type, member)
+#define __m(type, name, bits) type name : bits; /* define the struct member with bits width */
+#define __m1(type, name) type name;				/* define the struct member, which consume a type width */
 ```
+And this define how to parse the struct member:
+```
+#define __m(type, name, bits)                                                                 \
+	dr->name = TS_READ_BITS_##type(buf + bytes_off, bits, bits_off);                          \
+	bits_off += bits;                                                                         \
+	if (bits_off == sizeof(type) * 8) {                                                       \
+		bits_off = 0;                                                                         \
+		bytes_off += sizeof(type);                                                            \
+	}
+
+#define __m1(type, name)                                                                      \
+	if (bytes_off < len) {                                                                    \
+		dr->name = TS_READ_##type(buf + bytes_off);                                           \
+		bytes_off += sizeof(type); }
+```
+We should implement macros for free and dump too.
+Every macro should be well defined for the four helper types.
+see ```include/descriptor.h```
+
+Also, not every sub-structrue of a descriptor is defined as above. A simple TLV is not enough,
+macro define could be too compilated.
+If we do have many descriptors share the same pattern, we can do things like below
+```
+define __mplast_custom_sub(type, name, parser_cb, dump_cb, free_cb)
+```
+we can add all parse, dump and free functions as callback here.
+
+If we don't have many structures share the same pattern, just write functions for it.
+And add initialization for descriptors in ```init_descriptor_parsers``` function.