{"type":"doc","content":[{"type":"paragraph","content":[{"text":"In the final two weeks, we are going to bring it all together in an embedded development case study. We will use parts of the previous practicals as well as some content from the lectures to create a system which:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Uses FreeRTOS as its operating system to give us multitasking and easier programming.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Uses lwIP and Ethernet networking to read messages from the network.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Passes those messages into a custom IP core which calculates their MD5 hash.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Coordinates all of this over a serial interface to the user.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Displays animated graphics over HDMI.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Part 1 - FreeRTOS","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Setup","type":"text"}]},{"type":"paragraph","content":[{"text":"First, let’s start playing with FreeRTOS. As you will remember from the lectures, FreeRTOS is a lightweight real-time operating system that provides tasking and priority-based scheduling.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Vitis, create a new application project and when it asks which Platform to use, select your hardware project from the previous practical in which we deployed your Collatz Conjecture evaluation IP.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Call the project something sensible like ","type":"text"},{"text":"freertos_practical","type":"text","marks":[{"type":"code"}]},{"text":" and select \"Create new...\" to create a new System.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When it asks you to select a Domain (where do you want your code to run) select “Create new..” and set the operating system to ","type":"text"},{"text":"freertos10_xilinx","type":"text","marks":[{"type":"code"}]},{"text":" and the cpu to ","type":"text"},{"text":"ps7_cortexa9_0","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Select “Empty application” (or the C++ version if you want) and Finish.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Now we will need to include the lwIP library. It might already have been added by the tools but we can check by doing:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Double click on ","type":"text"},{"text":"freertos_practical.prj","type":"text","marks":[{"type":"code"}]},{"text":" and click Navigate to BSP settings. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Ensure the Board Support Package for your Domain ","type":"text"},{"text":"freertos10_xilinx_ps7_cortexa9_0","type":"text","marks":[{"type":"code"}]},{"text":" is selected and click Modify BSP settings.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Ensure that ","type":"text"},{"text":"lwip211","type":"text","marks":[{"type":"code"}]},{"text":" is checked","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Important:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}},{"type":"strong"}]},{"text":" You must also go to the lwIP settings and make the following two changes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"api_mode","type":"text","marks":[{"type":"code"}]},{"text":" set to ","type":"text"},{"text":"SOCKET API","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"dhcp_options.lwip_dhcp","type":"text","marks":[{"type":"code"}]},{"text":" set to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":395,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":395,"alt":"Untitled.png","id":"2409402c-5af0-4b69-b1ac-76ccab1511af","collection":"contentId-54843634","type":"file","height":252}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Now we can add our code. In the Explorer pane, under the ","type":"text"},{"text":"freertos_practical/src","type":"text","marks":[{"type":"code"}]},{"text":" directory, right click and select New File and create two files, ","type":"text"},{"text":"main.c","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"network.c","type":"text","marks":[{"type":"code"}]},{"text":". Copy in the contents from here:","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"paragraph","content":[{"text":"main.c","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"#include \n#include \n\n#include \"xparameters.h\"\n#include \"netif/xadapter.h\"\n#include \"xuartps_hw.h\"\n#include \"xil_printf.h\"\n#include \"FreeRTOS.h\"\n#include \"task.h\"\n\n#include \"lwip/sockets.h\"\n#include \"lwipopts.h\"\n#include \n#include \n#include \n\n#define THREAD_STACKSIZE 1024\n#define PORT 51000\n\n//Put your MAC address here!\nunsigned char mac_ethernet_address[] = { 0xxx, 0xxx, 0xxx, 0xxx, 0xxx, 0xxx};\n\n//Function Prototypes\nvoid network_init(unsigned char* mac_address, lwip_thread_fn app);\nvoid application_task(void *);\nvoid udp_get_handler(void *arg, struct udp_pcb *pcb, struct pbuf *p, const ip_addr_t *addr, u16_t port);\n\n//------\n\nint main()\n{\n\t//Initialise the network with our MAC address, and the function that should be started as a FreeRTOS task\n\tnetwork_init(mac_ethernet_address, application_task);\n\n\tvTaskStartScheduler(); //Start the scheduler\n\n\t//we will only get to here if someone calls vTaskEndScheduler()\n\treturn 0;\n}\n\nvoid application_task(void *p) {\n //This task will set things up and then remove itself once that is done\n\txil_printf(\"application_task started\\n\\r\");\n\n\t//Bind a network receiver as we did before\n\tstruct udp_pcb *recv_pcb = udp_new();\n\tudp_bind(recv_pcb, IP_ADDR_ANY, PORT);\n\tudp_recv(recv_pcb, udp_get_handler, NULL);\n\n //Create any other tasks you might need here\n //...\n //...\n\n\tvTaskDelete(NULL); //Set up complete so delete ourselves\n}\n\nvoid udp_get_handler(void *arg, struct udp_pcb *pcb, struct pbuf *p, const ip_addr_t *addr, u16_t port) {\n if (p) {\n char msg[p->len + 1];\n memcpy(msg, p->payload, p->len);\n msg[p->len] = '\\0';\n printf(\"Message: %s\\n\", msg);\n pbuf_free(p);\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"network.c","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"#include \n#include \"xparameters.h\"\n#include \"netif/xadapter.h\"\n#include \"xil_printf.h\"\n\n#include \"lwip/dhcp.h\"\nvoid lwip_init();\n\n#define THREAD_STACKSIZE 1024\n\n//Function prototypes\nvoid print_ip(const char *msg, const ip_addr_t *ip);\nvoid network_thread(void *p);\nint network_startup_task();\n\n//Structures and globals\nstatic struct netif server_netif;\nstruct netif *echo_netif;\nunsigned char* mac_addr;\nlwip_thread_fn application_task;\nTaskHandle_t startuptask, nettask, apptask, rcv_task;\n\n//---------------\n\n//Initialise network task \n//This is called by user code to provide the mac address we should use,\n//and the code that we should run once the network is ready.\nvoid network_init(unsigned char* mac_address, lwip_thread_fn app) {\n\tmac_addr = mac_address;\n\tapplication_task = app;\n\txTaskCreate((lwip_thread_fn) network_startup_task, \"startup_task\", THREAD_STACKSIZE, NULL, DEFAULT_THREAD_PRIO, &startuptask);\n}\n\n//Created by network_init(). Initialises lwIP, runs DHCP, and once connected, starts the application_task that the user provided\n//when they called network_init\nint network_startup_task()\n{\n lwip_init();\n\n //Create lwIP's network handling thread (as described by lwIP documentation)\n xTaskCreate(network_thread, \"nw_task\", THREAD_STACKSIZE, NULL, DEFAULT_THREAD_PRIO, &nettask);\n\n //This task just waits until we get an IP address via DHCP, then creates our application task\n while (1) {\n \tvTaskDelay(DHCP_FINE_TIMER_MSECS / portTICK_RATE_MS); //wait 500ms\n\t\tif (server_netif.ip_addr.addr) { //Do we have an IP address?\n\t\t\txil_printf(\"DHCP request success\\r\\n\");\n\t\t\tprint_ip(\"Board IP: \", &server_netif.ip_addr);\n\t\t\tprint_ip(\"Netmask : \", &server_netif.netmask);\n\t\t\tprint_ip(\"Gateway : \", &server_netif.gw);\n\t\t\txil_printf(\"\\r\\n\");\n\t\t\txTaskCreate(application_task, \"app_task\", THREAD_STACKSIZE, NULL, DEFAULT_THREAD_PRIO, &apptask);\n\t\t\tbreak;\n\t\t}\n\t}\n\n //DHCP is connected and we've created the main task so delete ourselves\n vTaskDelete(NULL); //Passing NULL says to delete this task\n return 0;\n}\n\n//lwIP's network handling thread (as described by lwIP documentation)\n//Started from the network_startup_task\nvoid network_thread(void *p)\n{\n struct netif *netif = &server_netif;\n ip_addr_t ipaddr, netmask, gw;\n int mscnt = 0;\n\n\tipaddr.addr = 0;\n\tgw.addr = 0;\n\tnetmask.addr = 0;\n\n // Add our network interface to lwIP and set it as default\n if (!xemac_add(netif, &ipaddr, &netmask, &gw, mac_addr, XPAR_XEMACPS_0_BASEADDR)) {\n \txil_printf(\"Error adding network interface\\r\\n\");\n \treturn;\n }\n netif_set_default(netif);\n netif_set_up(netif);\n\n // Start packet receive thread, this is part of lwIP\n xTaskCreate((void(*)(void*))xemacif_input_thread, \"xemacif_input_thread\", THREAD_STACKSIZE, netif, DEFAULT_THREAD_PRIO, &rcv_task);\n\n // Start DHCP. This task will now loop forever calling dhcp_fine_tmr and dhcp_coarse_tmr every so often\n xil_printf(\"\\r\\nStart DHCP lookup...\\r\\n\");\n dhcp_start(netif);\n while (1) {\n\t\tvTaskDelay(DHCP_FINE_TIMER_MSECS / portTICK_RATE_MS);\n\t\tdhcp_fine_tmr();\n\t\tmscnt += DHCP_FINE_TIMER_MSECS;\n\t\tif (mscnt >= DHCP_COARSE_TIMER_SECS*1000) {\n\t\t\tdhcp_coarse_tmr();\n\t\t\tmscnt = 0;\n\t\t}\n\t}\n\n return;\n}\n\nvoid print_ip(const char *msg, const ip_addr_t *ip)\n{\n\txil_printf(msg);\n\txil_printf(\"%d.%d.%d.%d\\n\\r\", ip4_addr1(ip), ip4_addr2(ip), ip4_addr3(ip), ip4_addr4(ip));\n}","type":"text"}]},{"type":"paragraph"}]},{"type":"paragraph","content":[{"text":"Remember to change the MAC address at the top of ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}}]},{"text":"main.c","type":"text","marks":[{"type":"code"}]},{"text":"!","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}}]}]},{"type":"paragraph","content":[{"text":"Most of this code is the same as what we used in ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://uoy.atlassian.net/wiki/spaces/RTS/pages/35688834"}},{"text":". However you will note that it is now wrapped in FreeRTOS tasks instead of all just being in the ","type":"text"},{"text":"main()","type":"text","marks":[{"type":"code"}]},{"text":" function. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you have put your MAC address in the code, this should listen for Cat Facts as before and will print the facts out on the screen. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Extending the tasking","type":"text"}]},{"type":"paragraph","content":[{"text":"Now extend the application to add two additional tasks. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"leds_task","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A task which lights up the LEDs when the buttons are pressed, like we did all the way back in ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://uoy.atlassian.net/wiki/spaces/RTS/pages/35688800"}},{"text":" ","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ui_task","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A task which allows the user to enter messages from the serial and send them to other people on the network, like we did in ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://uoy.atlassian.net/wiki/spaces/RTS/pages/35688834"}},{"text":" ","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"You can look inside ","type":"text"},{"text":"network.c","type":"text","marks":[{"type":"code"}]},{"text":" to see how FreeRTOS tasks are created, or look in the ","type":"text"},{"text":"FreeRTOS reference manual","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.freertos.org/Documentation/FreeRTOS_Reference_Manual_V10.0.0.pdf"}}]},{"text":". Now, instead of having to create fiddly state machines, keep track of lots of global state variables, and remembering to always call ","type":"text"},{"text":"handle_ethernet()","type":"text","marks":[{"type":"code"}]},{"text":" we can finally handle multiple jobs cleanly in separate tasks.","type":"text"}]},{"type":"paragraph","content":[{"text":"Hint: Remember that FreeRTOS will run whichever task is the highest priority and is runnable. If a task is always runnable, it will always run. Use delays to ","type":"text","marks":[{"type":"em"}]},{"text":"avoid starving ","type":"text","marks":[{"type":"em"},{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Starvation_(computer_science)"}}]},{"text":"other tasks. ","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Part 2 - Custom hardware for MD5 hashing","type":"text"}]},{"type":"paragraph","content":[{"text":"Now that our OS is working, we are going to create a new custom IP core which we can use to get the ","type":"text"},{"text":"MD5 hash","type":"text","marks":[{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/MD5"}}]},{"text":" of a string of text. Once this is working, we will then operate this IP core from another FreeRTOS task. First, the IP core.","type":"text"}]},{"type":"paragraph","content":[{"text":"One of the strengths of HLS is that it can work with almost any C code. In this practical we are going to take a software algorithm from the internet and turn it into a hardware co-processor that can calculate MD5 hashes. Do not worry about trying to understand the implementation details of MD5; it is enough to know that it takes input data and hashes it to a 16-byte hash value. To start with, copy the following example C implementation of MD5 (adapted from example code ","type":"text"},{"text":"previously on Wikipedia","type":"text","marks":[{"type":"link","attrs":{"href":"http://en.wikipedia.org/w/index.php?title=MD5&oldid=611986848#Simple_implementation"}}]},{"text":"). Your task is to get this code compiling through Vitis HLS to create an AXI peripheral that can be used by the ARM to hash some example data. You can check that your output is correct with an online tool, ","type":"text"},{"text":"such as this one","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.adamek.biz/md5-generator.php"}}]},{"text":".","type":"text"}]},{"type":"expand","attrs":{"title":"md5.c"},"content":[{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"/*\n * Simple MD5 implementation\n *\n * Compile with: gcc -o md5 md5.c\n */\n#include \n#include \n#include \n#include \n \n// Constants are the integer part of the sines of integers (in radians) * 2^32.\nconst uint32_t k[64] = {\n0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee ,\n0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501 ,\n0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be ,\n0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821 ,\n0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa ,\n0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8 ,\n0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed ,\n0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a ,\n0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c ,\n0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70 ,\n0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05 ,\n0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665 ,\n0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039 ,\n0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1 ,\n0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1 ,\n0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391 };\n \n// r specifies the per-round shift amounts\nconst uint32_t r[] = {7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,\n 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,\n 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,\n 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21};\n \nuint32_t left_rotate(uint32_t x, uint32_t c) {\n return (x << c) | (x >> (32 - c));\n}\n \nvoid to_bytes(uint32_t val, uint8_t *bytes)\n{\n bytes[0] = (uint8_t) val;\n bytes[1] = (uint8_t) (val >> 8);\n bytes[2] = (uint8_t) (val >> 16);\n bytes[3] = (uint8_t) (val >> 24);\n}\n \nuint32_t to_int32(const uint8_t *bytes)\n{\n return (uint32_t) bytes[0]\n | ((uint32_t) bytes[1] << 8)\n | ((uint32_t) bytes[2] << 16)\n | ((uint32_t) bytes[3] << 24);\n}\n \nvoid md5(const uint8_t *initial_msg, size_t initial_len, uint8_t *digest) {\n \n // These vars will contain the hash\n uint32_t h0, h1, h2, h3;\n \n // Message (to prepare)\n uint8_t *msg = NULL;\n \n size_t new_len, offset;\n uint32_t w[16];\n uint32_t a, b, c, d, i, f, g, temp;\n \n // Initialize variables - simple count in nibbles:\n h0 = 0x67452301;\n h1 = 0xefcdab89;\n h2 = 0x98badcfe;\n h3 = 0x10325476;\n \n //Pre-processing:\n //append \"1\" bit to message \n //append \"0\" bits until message length in bits ≡ 448 (mod 512)\n //append length mod (2^64) to message\n \n for (new_len = initial_len + 1; new_len % (512/8) != 448/8; new_len++);\n \n msg = malloc(new_len + 8);\n memcpy(msg, initial_msg, initial_len);\n msg[initial_len] = 0x80; // append the \"1\" bit; most significant bit is \"first\"\n for (offset = initial_len + 1; offset < new_len; offset++)\n msg[offset] = 0; // append \"0\" bits\n \n // append the len in bits at the end of the buffer.\n to_bytes(initial_len*8, msg + new_len);\n // initial_len>>29 == initial_len*8>>32, but avoids overflow.\n to_bytes(initial_len>>29, msg + new_len + 4);\n \n // Process the message in successive 512-bit chunks:\n //for each 512-bit chunk of message:\n for(offset=0; offset

Browser not supported