From 234729507ee07174237908cd5d78cc4d1c740369 Mon Sep 17 00:00:00 2001
From: Kurt Van Dijck <kurt@vandijck-laurijssen.be>
Date: Thu, 28 Nov 2013 09:56:54 +0100
Subject: [PATCH] j1939.page: add relevant API calls

---
 j1939.page | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/j1939.page b/j1939.page
index 9ab6ba4..f9c593e 100644
--- a/j1939.page
+++ b/j1939.page
@@ -152,6 +152,10 @@ Most of the subsequent examples will use 2 sockets programs (in 2 terminals).
 One will use CAN_J1939 sockets using *testj1939*,
 and the other will use CAN_RAW sockets using cansend+candump.
 
+Where I think it's relevant, I added the core API calls that *testj1939* used
+because *testj1939* may look too generic to appreciate the degree of control
+that the API exposes.
+
 ### receive without source address
 
 Do in terminal 1
@@ -177,6 +181,14 @@ In J1939, this means that ECU 0x40 sends directly to ECU 0x41
 Since we did not bind to address 0x41, this traffic
 is not meant for us and *testj1939* does not receive it.
 
+*testj1939* used these calls:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+	while (1)
+		ret = recvfrom(sock, dat, sizeof(dat), 0,
+				(void *)&peername, &peernamelen);
+
 ### Use source address
 
 	./testj1939 can0:0x80
@@ -230,6 +242,12 @@ This produces **1BFFFF80#0123456789ABCDEF** on CAN.
 will produce exactly the same because **0x80** is the only
 address currently assigned to **can0:** and is used by default.
 
+*testj1939* used these calls:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+			ret = send(sock, dat, todo_send, 0);
+
 ### Multiple source addresses on 1 CAN device
 
 	ip addr add j1939 0x90 dev can0
@@ -279,6 +297,13 @@ Specifing one during bind is therefore sufficient.
 
 emits the very same.
 
+*testj1939* used these calls:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+			ret = sendto(sock, dat, todo_send, 0,
+					(void *)&peername, sizeof(peername));
+
 ### Emit different PGNs using the same socket
 
 The PGN is provided in both __bind( *sockname* )__ and
@@ -299,6 +324,13 @@ emits **1B214080#0123456789ABCDEF** .
 
 It makes sometimes sense to omit the PGN in __bind( *sockname* )__ .
 
+*testj1939* used these calls, even for the broadcasted transmission:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+			ret = sendto(sock, dat, todo_send, 0,
+					(void *)&peername, sizeof(peername));
+
 ### Larger packets
 
 J1939 transparently switches to *Transport Protocol* when packets
@@ -313,6 +345,13 @@ emits:
 	18EBFF80#02EF0123456789AB
 	18EBFF80#03CDEF01234567
 
+*testj1939* used these same calls:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+			ret = sendto(sock, dat, todo_send, 0,
+					(void *)&peername, sizeof(peername));
+
 The fragments for broadcasted *Transport Protocol* are seperated
 __50ms__ from each other.  
 Destination specific *Transport Protocol* applies flow control
@@ -344,6 +383,14 @@ emits
 	1801FF80#0123456789ABCDEF	
 	0C02FF80#0123456789ABCDEF
 
+*testj1939* used these calls for modified priority:
+
+	sock = ret = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
+		ret = setsockopt(sock, SOL_CAN_J1939, SO_J1939_SEND_PRIO,
+				&todo_prio, sizeof(todo_prio));
+	ret = bind(sock, (void *)&sockname, sizeof(sockname));
+			ret = send(sock, dat, todo_send, 0);
+
 ### using connect
 
 ### advanced filtering